morph

README

morph

A compact package for organizing and maintaining your entity database metadata.

What is it?

morph organizes and maintains the necessary metadata to map your entities to and from relational database tables. This is accomplished using the Metadata Mapping pattern popularized by Martin Fowler. With these metadata mappings, your application is empowered to construct SQL queries dynamically using the entities themselves.

Why use it?

With morph, your application reaps several benefits:

• dynamic construction of queries using entities and their fields.
• metadata generation using files in several formats, including YAML and JSON.
• decoupling of code responsible for manufacturing queries from code tasked with SQL generation.

How to use it?

Using morph is super straightforward. You utilize Table and Column to organize metadata for your entities and their associated relational representations. Let's suppose you have a User entity in your application (user):

var usernameCol morph.Column
usernameCol.SetName("username")
usernameCol.SetField(Fields.Username)

var passwordCol morph.Column
passwordCol.SetName("password")
passwordCol.SetField(Fields.Password)

var userTable morph.Table
userTable.SetName("user")
userTable.SetAlias("U")
userTable.SetType(user)
userTable.AddColumns(usernameCol, passwordCol)

Loading

Capturing the metadata mappings can be tedious, especially if your application has many entities with corresponding relational representations. Instead of constructing them manually, we recommend loading in a file that specifies the metadata mapping configuration:

{
  "tables": [
    {
      "typeName": "example.User",
      "name": "user",
      "alias": "U",
      "columns": [
        {
          "name": "username",
          "field": "Username"
        },
        {
          "name": "password",
          "field": "Password"
        }
      ]
    }
  ]
}

configuration, err := morph.Load("./metadata.json")
if err != nil {
	panic(err)
}

tables := configuration.AsMetadata()

Custom Loader

At this time, we currently support YAML (.yaml, .yml) and JSON (.json) configuration files. However, if you would like to utilize a different file format, you can construct a type that implements morph.Loader and add the appropriate entries in morph.Loaders. The morph.Load function will leverage morph.Loaders by extracting the file extension using the path provided to it.

Contribute

Want to lend us a hand? Check out our guidelines for contributing.

License

We are rocking an Apache 2.0 license for this project.

Code of Conduct

Please check out our code of conduct to get up to speed how we do things.

Documentation

Index

• Variables
• type Column
  • func (c *Column) Field() string
  • func (c *Column) Name() string
  • func (c *Column) SetField(field string)
  • func (c *Column) SetName(name string)
• type ColumnConfiguration
• type Configuration
  • func Load(path string) (Configuration, error)
  • func (c Configuration) AsMetadata() []Table
• type JSONLoader
  • func (l JSONLoader) Load(path string) (c Configuration, err error)
• type Loader
• type Table
  • func (t *Table) AddColumn(column Column) error
  • func (t *Table) AddColumns(columns ...Column) error
  • func (t *Table) Alias() string
  • func (t *Table) ColumnName(field string) (string, error)
  • func (t *Table) ColumnNames() []string
  • func (t *Table) Columns() []Column
  • func (t *Table) FieldName(name string) (string, error)
  • func (t *Table) Name() string
  • func (t *Table) SetAlias(alias string)
  • func (t *Table) SetName(name string)
  • func (t *Table) SetType(entity interface{})
  • func (t *Table) SetTypeName(typeName string)
  • func (t *Table) TypeName() string
• type TableConfiguration
• type YAMLLoader
  • func (l YAMLLoader) Load(path string) (c Configuration, err error)

Variables

var Loaders = map[string]Loader{
	"yaml": YAMLLoader{},
	"yml":  YAMLLoader{},
	"json": JSONLoader{},
}

Loaders is the collection of loaders by file extension.

Types

type Column

type Column struct {
	// contains filtered or unexported fields
}

Column represents a mapping between an entity field and a database column.

func (*Column) Field

func (c *Column) Field() string

Field retrieves the field name associated to the column.

func (*Column) Name

func (c *Column) Name() string

Name retrieves the name of the column.

func (*Column) SetField

func (c *Column) SetField(field string)

SetField modifies the field name associated to the column.

func (*Column) SetName

func (c *Column) SetName(name string)

SetName modifies the name of the column.

type ColumnConfiguration

type ColumnConfiguration struct {
	Name  string `json:"name" yaml:"name"`
	Field string `json:"field" yaml:"field"`
}

ColumnConfiguration represents the configuration used to construct a single column mapping.

type Configuration

type Configuration struct {
	Tables []TableConfiguration `json:"tables" yaml:"tables"`
}

Configuration represents the configuration used to construct the table and column mappings.

func Load

func Load(path string) (Configuration, error)

Load loads the configuration from the provided file.

func (Configuration) AsMetadata

func (c Configuration) AsMetadata() []Table

AsMetadata converts the configuration to metadata mappings.

type JSONLoader

type JSONLoader struct{}

func (JSONLoader) Load

func (l JSONLoader) Load(path string) (c Configuration, err error)

Load loads the configuration from the JSON file provided.

type Loader

type Loader interface {
	Load(path string) (Configuration, error)
}

Loader loads the cofiguration from the provided file.

type Table

type Table struct {
	// contains filtered or unexported fields
}

Table represents a mapping between an entity and a database table.

func (*Table) AddColumn

func (t *Table) AddColumn(column Column) error

AddColumn adds a column to the table.

func (*Table) AddColumns

func (t *Table) AddColumns(columns ...Column) error

AddColumns adds all of the provided columns to the table.

func (*Table) Alias

func (t *Table) Alias() string

Alias retrieves the alias for the table.

func (*Table) ColumnName

func (t *Table) ColumnName(field string) (string, error)

ColumnName retrieves the column name associated to the provide field name.

func (*Table) ColumnNames

func (t *Table) ColumnNames() []string

ColumnNames retrieves all of the column names for the table.

func (*Table) Columns

func (t *Table) Columns() []Column

Columns retrieves all of the columns for the table.

func (*Table) FieldName

func (t *Table) FieldName(name string) (string, error)

FieldName retrieves the field name associated to the provided column name.

func (*Table) Name

func (t *Table) Name() string

Name retrieves the the table name.

func (*Table) SetAlias

func (t *Table) SetAlias(alias string)

SetAlias modifies the alias of the table.

func (*Table) SetName

func (t *Table) SetName(name string)

SetName modifies the name of the table.

func (*Table) SetType

func (t *Table) SetType(entity interface{})

SetType associates the entity type to the table.

func (*Table) SetTypeName

func (t *Table) SetTypeName(typeName string)

SetTypeName modifies the entity type name for the table.

func (*Table) TypeName

func (t *Table) TypeName() string

TypeName retrieves the type name of the entity associated to the table.

type TableConfiguration

type TableConfiguration struct {
	TypeName string                `json:"typeName" yaml:"typeName"`
	Name     string                `json:"name" yaml:"name"`
	Alias    string                `json:"alias" yaml:"alias"`
	Columns  []ColumnConfiguration `json:"columns" yaml:"columns"`
}

TableConfiguration represents the configuration used to construct a single table mapping.

type YAMLLoader

type YAMLLoader struct{}

func (YAMLLoader) Load

func (l YAMLLoader) Load(path string) (c Configuration, err error)

Load loads the configuration from the YAML file provided.