godal

README

godal

Generic Database Access Layer library for Go (Golang).

Feature overview

• Interface for generic business object (BO) and data access object (DAO).
• Generic BO implementation.
• Generic DAO implementation for AWS DynamoDB.
• Generic DAO implementation for Azure Cosmos DB.
  • database/sql implementation.
• Generic DAO implementation for MongoDB.
• Generic DAO implementation for database/sql. Ready-to-use implementations:
  • MSSQL
  • MySQL
  • Oracle
  • PostgreSQL
  • SQLite3

Installation

go get github.com/btnguyen2k/godal

Usage & Documentation

• 
• Samples: see examples and examples_sta
• Wiki

Contributing

Use Github issues for bug reports and feature requests.

Contribute by Pull Request:

1. Fork Godal on github (https://help.github.com/articles/fork-a-repo/)
2. Create a topic branch (git checkout -b my_branch)
3. Implement your change
4. Push to your branch (git push origin my_branch)
5. Post a pull request on github (https://help.github.com/articles/creating-a-pull-request/)

License

MIT - see LICENSE.md.

Documentation

Overview

Package godal provides a skeleton to implement generic data-access-layer in Golang.

Index

• Constants
• Variables
• type AbstractGenericDao
  • func NewAbstractGenericDao(gdao IGenericDao) *AbstractGenericDao
  • func (dao *AbstractGenericDao) GetRowMapper() IRowMapper
  • func (dao *AbstractGenericDao) SetRowMapper(rowMapper IRowMapper) *AbstractGenericDao
• type FilterOperator
• type FilterOpt
  • func MakeFilter(input map[string]interface{}) FilterOpt
• type FilterOptAnd
  • func (f *FilterOptAnd) Add(filter FilterOpt) *FilterOptAnd
• type FilterOptFieldIsNotNull
• type FilterOptFieldIsNull
• type FilterOptFieldOpField
• type FilterOptFieldOpValue
• type FilterOptOr
  • func (f *FilterOptOr) Add(filter FilterOpt) *FilterOptOr
• type GenericBo
  • func (bo *GenericBo) Checksum() []byte
  • func (bo *GenericBo) GboFromJson(js []byte) error
  • func (bo *GenericBo) GboGetAttr(path string, typ reflect.Type) (interface{}, error)
  • func (bo *GenericBo) GboGetAttrUnmarshalJson(path string) (interface{}, error)
  • func (bo *GenericBo) GboGetAttrUnsafe(path string, typ reflect.Type) interface{}
  • func (bo *GenericBo) GboGetTimeWithLayout(path, layout string) (time.Time, error)
  • func (bo *GenericBo) GboImportViaJson(src interface{}) error
  • func (bo *GenericBo) GboImportViaMap(src map[string]interface{}) error
  • func (bo *GenericBo) GboIterate(callback func(kind reflect.Kind, field interface{}, value interface{}))
  • func (bo *GenericBo) GboSetAttr(path string, value interface{}) error
  • func (bo *GenericBo) GboToJson() ([]byte, error)
  • func (bo *GenericBo) GboToJsonUnsafe() []byte
  • func (bo *GenericBo) GboTransferViaJson(dest interface{}) error
• type IGenericBo
  • func NewGenericBo() IGenericBo
• type IGenericDao
• type IRowMapper
• type SortingField
  • func (sf *SortingField) ToSortingOpt() *SortingOpt
• type SortingOpt
  • func (so *SortingOpt) Add(fields ...*SortingField) *SortingOpt

Constants

const (
	// Version of godal
	Version = "0.6.0"
)

Variables

var (
	// ErrGdaoDuplicatedEntry indicates that the write operation failed because of data integrity violation: entry/key duplicated.
	ErrGdaoDuplicatedEntry = errors.New("data integrity violation: duplicated entry/key")
)

var NilValue nilValue = nil

NilValue represents a nil/null value.

Available: since v0.2.4

Types

type AbstractGenericDao

type AbstractGenericDao struct {
	IGenericDao
	// contains filtered or unexported fields
}

AbstractGenericDao is an abstract implementation of IGenericDao.

Function implementations (n = No, y = Yes, i = inherited):

• (n) GdaoCreateFilter(storageId string, bo IGenericBo) FilterOpt
• (n) GdaoDelete(storageId string, bo IGenericBo) (int, error)
• (n) GdaoDeleteMany(storageId string, filter FilterOpt) (int, error)
• (n) GdaoFetchOne(storageId string, filter FilterOpt) (IGenericBo, error)
• (n) GdaoFetchMany(storageId string, filter FilterOpt, sorting *SortingOpt, startOffset, numItems int) ([]IGenericBo, error)
• (n) GdaoCreate(storageId string, bo IGenericBo) (int, error)
• (n) GdaoUpdate(storageId string, bo IGenericBo) (int, error)
• (n) GdaoSave(storageId string, bo IGenericBo) (int, error)

func NewAbstractGenericDao

func NewAbstractGenericDao(gdao IGenericDao) *AbstractGenericDao

NewAbstractGenericDao constructs a new 'AbstractGenericDao' instance.

func (*AbstractGenericDao) GetRowMapper

func (dao *AbstractGenericDao) GetRowMapper() IRowMapper

GetRowMapper implements IGenericDao.GetRowMapper.

Available since v0.0.2.

func (*AbstractGenericDao) SetRowMapper

func (dao *AbstractGenericDao) SetRowMapper(rowMapper IRowMapper) *AbstractGenericDao

SetRowMapper attaches an IRowMapper to the DAO for latter use.

Available since v0.0.2.

type FilterOperator

type FilterOperator int

FilterOperator represents an operator used in filter.

Available since v0.5.0

const (
	// FilterOpEqual is "equal" operator
	FilterOpEqual FilterOperator = iota
	// FilterOpNotEqual is "not equal" operator
	FilterOpNotEqual

	// FilterOpGreater is "greater" operator
	FilterOpGreater
	// FilterOpGreaterOrEqual is "greater or equal operator
	FilterOpGreaterOrEqual

	// FilterOpLess is "less than" operator
	FilterOpLess
	// FilterOpLessOrEqual is "less than or equal operator
	FilterOpLessOrEqual
)

type FilterOpt

type FilterOpt interface {
}

FilterOpt is the abstract interface for specifying filter.

Available since v0.5.0

func MakeFilter

func MakeFilter(input map[string]interface{}) FilterOpt

MakeFilter is helper function to build FilterOpt from an input map.

• input map is mapping of {field-name:field-value}.
• each filter element is built as <field-name> FilterOpEqual <value>.
• all filter elements are combined via FilterOptAnd.

Available since v0.5.0

type FilterOptAnd

type FilterOptAnd struct {
	Filters []FilterOpt
}

FilterOptAnd combines two or more filters using AND clause.

Available since v0.5.0

func (*FilterOptAnd) Add

func (f *FilterOptAnd) Add(filter FilterOpt) *FilterOptAnd

Add appends a filter to the list.

type FilterOptFieldIsNotNull

type FilterOptFieldIsNotNull struct {
	FieldName string
}

FilterOptFieldIsNotNull represents single filter: <field> IS NOT NULL.

type FilterOptFieldIsNull

type FilterOptFieldIsNull struct {
	FieldName string
}

FilterOptFieldIsNull represents single filter: <field> IS NULL.

type FilterOptFieldOpField

type FilterOptFieldOpField struct {
	FieldNameLeft  string
	Operator       FilterOperator
	FieldNameRight string
}

FilterOptFieldOpField represents single filter: <field-left> <operator> <field-right>.

type FilterOptFieldOpValue

type FilterOptFieldOpValue struct {
	FieldName string
	Operator  FilterOperator
	Value     interface{}
}

FilterOptFieldOpValue represents single filter: <field> <operator> <value>.

type FilterOptOr

type FilterOptOr struct {
	Filters []FilterOpt
}

FilterOptOr combines two or more filters using OR clause.

Available since v0.5.0

func (*FilterOptOr) Add

func (f *FilterOptOr) Add(filter FilterOpt) *FilterOptOr

Add appends a filter to the list.

type GenericBo

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

GenericBo is a generic implementation of business-object.

Sample usage:

gbo := NewGenericBo()
gbo.GboSetAttr("name.first", "Thanh")
gbo.GboSetAttr("name.last", "Nguyen")

// reflect.TypeOf("any string") is equivalent to reddo.TypeString
firstName, err := gbo.GboGetAttr("name.first", reddo.TypeString)    // firstName = "Thanh"
lastName, err := gbo.GboGetAttr("name.last", reflect.TypeOf(""))    // lastName = "Nguyen"

gbo.GboSetAttr("age", 123)
age, err := gbo.GboGetAttr("age", reddo.TypeInt)    // age = 123

var m interface{}
err = gbo.GboTransferViaJson(&m)
// m = map[string]interface{}{
//   "age" : 123,
//   "name": map[string]interface{}{
//     "first": "Thanh",
//     "last" : "Nguyen",
//   },
// }

ext := map[string]interface{}{"year":2019, "month":"3", "active":true}
err = gbo.GboImportViaJson(ext)
year, err  := gbo.GboGetAttr("year", reddo.TypeString)    // year = "2019", because we want a string-result
month, err := gbo.GboGetAttr("month", reddo.TypeInt)      // month = 3, because we want an int-result and "3" is convertible to int
name, err := gbbo.GboGetAttr("name", nil)                 // name is nil because GboImportViaJson clear existing data upon importing

func (*GenericBo) Checksum

func (bo *GenericBo) Checksum() []byte

Checksum returns checksum value of the BO.

Available: since v0.0.4

func (*GenericBo) GboFromJson

func (bo *GenericBo) GboFromJson(js []byte) error

GboFromJson implements IGenericBo.GboFromJson.

• If error occurs, existing BO data is intact.
• If successful, existing data is replaced.

func (*GenericBo) GboGetAttr

func (bo *GenericBo) GboGetAttr(path string, typ reflect.Type) (interface{}, error)

GboGetAttr implements IGenericBo.GboGetAttr.

'type' can be nil. In that case, this function returns the result of type 'interface{}'.

func (*GenericBo) GboGetAttrUnmarshalJson

func (bo *GenericBo) GboGetAttrUnmarshalJson(path string) (interface{}, error)

GboGetAttrUnmarshalJson implements IGenericBo.GboGetAttrUnmarshalJson.

func (*GenericBo) GboGetAttrUnsafe

func (bo *GenericBo) GboGetAttrUnsafe(path string, typ reflect.Type) interface{}

GboGetAttrUnsafe implements IGenericBo.GboGetAttrUnsafe.

'type' can be nil. In that case, this function returns the result of type 'interface{}'.

func (*GenericBo) GboGetTimeWithLayout

func (bo *GenericBo) GboGetTimeWithLayout(path, layout string) (time.Time, error)

GboGetTimeWithLayout implements IGenericBo.GboGetTimeWithLayout.

If value does not exist at 'path', this function returns 'zero' time (e.g. time.Time{}).

func (*GenericBo) GboImportViaJson

func (bo *GenericBo) GboImportViaJson(src interface{}) error

GboImportViaJson implements IGenericBo.GboImportViaJson.

Existing data is removed upon importing.

func (*GenericBo) GboImportViaMap

func (bo *GenericBo) GboImportViaMap(src map[string]interface{}) error

GboImportViaMap implements IGenericBo.GboImportViaMap.

Existing data is removed upon importing.

func (*GenericBo) GboIterate

func (bo *GenericBo) GboIterate(callback func(kind reflect.Kind, field interface{}, value interface{}))

GboIterate implements IGenericBo.GboIterate.

• If the underlying data is a map, 'callback' is called for each map's entry with reflect.Map is passed as 'kind' parameter.
• If the underlying data is a slice or array, 'callback' is called for each entry with reflect.Slice is passed as 'kind' parameter.
• This function of type GenericBo does not support iterating on other data types.

func (*GenericBo) GboSetAttr

func (bo *GenericBo) GboSetAttr(path string, value interface{}) error

GboSetAttr implements IGenericBo.GboSetAttr.

Intermediate nodes along the path are automatically created.

func (*GenericBo) GboToJson

func (bo *GenericBo) GboToJson() ([]byte, error)

GboToJson implements IGenericBo.GboToJson.

func (*GenericBo) GboToJsonUnsafe

func (bo *GenericBo) GboToJsonUnsafe() []byte

GboToJsonUnsafe implements IGenericBo.GboToJsonUnsafe.

func (*GenericBo) GboTransferViaJson

func (bo *GenericBo) GboTransferViaJson(dest interface{}) error

GboTransferViaJson implements IGenericBo.GboTransferViaJson.

Passing by value won't work, so 'dest' must be a pointer.

type IGenericBo

type IGenericBo interface {
	// GboIterate iterates over all bo's top level fields.
	//   - If the underlying data is a map, 'callback' is called for each map's entry with reflect.Map is passed as 'kind' parameter.
	//   - If the underlying data is a slice or array, 'callback' is called for each entry with reflect.Slice is passed as 'kind' parameter.
	//
	// Available: since v0.0.2
	GboIterate(callback func(kind reflect.Kind, field interface{}, value interface{}))

	// GboGetAttr retrieves a bo's attribute.
	//   - If 'typ' is not nil, the attribute value is converted to the specified type upon being returned.
	//   - Otherwise, the attribute value is returned as-is.
	GboGetAttr(path string, typ reflect.Type) (interface{}, error)

	// GboGetAttrUnsafe retrieves a bo's attribute as GboGetAttr does, but error is ignored.
	//
	// Available: since v0.0.2
	GboGetAttrUnsafe(path string, typ reflect.Type) interface{}

	// GboGetAttrUnmarshalJson retrieves a bo's attribute, treats attribute value as JSON-encoded and parses it back to Go type.
	//
	// Available: since v0.2.0
	GboGetAttrUnmarshalJson(path string) (interface{}, error)

	// GboGetTimeWithLayout retrieves a bo's attribute as 'time.Time'.
	//
	// If value at 'path' is a datetime represented as a string, this function calls 'time.Parse(...)' to convert the value to 'time.Time' using 'layout'.
	GboGetTimeWithLayout(path, layout string) (time.Time, error)

	// GboSetAttr sets a bo's attribute.
	GboSetAttr(path string, value interface{}) error

	// GboToJson serializes bo's data to JSON string.
	GboToJson() ([]byte, error)

	// GboToJsonUnsafe serializes bo's data to JSON string, ignoring error if any.
	//
	// Available: since v0.1.1
	GboToJsonUnsafe() []byte

	// GboFromJson imports bo's data from a JSON string.
	GboFromJson(js []byte) error

	// GboTransferViaJson copies bo's data to the destination using JSON transformation.
	// Firstly, bo's data is marshaled to JSON data. Then the JSON data is unmarshaled to 'dest'.
	//
	// Note: 'dest' must be a pointer because passing value does not work.
	GboTransferViaJson(dest interface{}) error

	// GboImportViaJson imports bo's data from an external source using JSON transformation.
	// Firstly, src is marshaled to JSON data. Then the JSON data is unmarshaled/imported to bo's attributes.
	GboImportViaJson(src interface{}) error

	// GboImportViaMap imports bo's data from an external map.
	//
	// Available: since v0.4.0
	GboImportViaMap(src map[string]interface{}) error
}

IGenericBo defines API interface of a generic business object.

The API interface assumes bo's data is stored in a hierarchy structure. A bo's attribute value is at the leaf node, and located via a 'path', for example "options.workhour[0].value".

Sample usage: see GenericBo.

func NewGenericBo

func NewGenericBo() IGenericBo

NewGenericBo constructs a new 'IGenericBo' instance.

type IGenericDao

type IGenericDao interface {
	// GdaoCreateFilter creates a filter object to match exactly one specific BO.
	GdaoCreateFilter(storageId string, bo IGenericBo) FilterOpt

	// GdaoDelete removes the specified BO from database store and returns the number of effected items.
	//
	// Upon successful call, this function returns 1 if the BO is removed, and 0 if the BO does not exist.
	GdaoDelete(storageId string, bo IGenericBo) (int, error)

	// GdaoDeleteMany removes many BOs from database store at once and returns the number of effected items.
	//
	// Upon successful call, this function may return 0 if no BO matches the filter.
	GdaoDeleteMany(storageId string, filter FilterOpt) (int, error)

	// GdaoFetchOne fetches one BO from database store.
	//
	// Filter should match exactly one BO. If there are more than one BO matching the filter, only the first one is returned.
	GdaoFetchOne(storageId string, filter FilterOpt) (IGenericBo, error)

	// GdaoFetchMany fetches many BOs from database store and returns them as a list.
	//
	// startOffset (0-based) and numItems are for paging. numItems <= 0 means no limit. Be noted that some databases do not support startOffset nor paging at all.
	GdaoFetchMany(storageId string, filter FilterOpt, sorting *SortingOpt, startOffset, numItems int) ([]IGenericBo, error)

	// GdaoCreate persists one BO to database store and returns the number of saved items.
	//
	// If the BO already existed, this function does not modify the existing one and should return (0, ErrGdaoDuplicatedEntry).
	GdaoCreate(storageId string, bo IGenericBo) (int, error)

	// GdaoUpdate updates one existing BO and returns the number of updated items.
	//
	// If the BO does not exist, this function does not create new BO and should return (0, nil).
	// If update causes data integrity violation, this function should return (0, ErrGdaoDuplicatedEntry).
	GdaoUpdate(storageId string, bo IGenericBo) (int, error)

	// GdaoSave persists one BO to database store and returns the number of saved items.
	//
	// If the BO already existed, this function replaces the existing one; otherwise new BO is created.
	// If data integrity violation occurs, this function should return (0, ErrGdaoDuplicatedEntry)
	GdaoSave(storageId string, bo IGenericBo) (int, error)

	// GetRowMapper returns the IRowMapper associated with the DAO.
	//
	// Available since v0.3.0.
	GetRowMapper() IRowMapper
}

IGenericDao defines API interface of a generic data-access-object.

Sample usage: see AbstractGenericDao for an abstract implementation of IGenericDao.

type IRowMapper

type IRowMapper interface {
	// ToRow transforms a IGenericBo to a row data suitable for persisting to database store.
	ToRow(storageId string, bo IGenericBo) (interface{}, error)

	// ToBo transforms a database row to IGenericBo.
	ToBo(storageId string, row interface{}) (IGenericBo, error)

	// ColumnsList returns list of a column names corresponding to a database store.
	ColumnsList(storageId string) []string

	// ToDbColName maps a IGenericBo field name to the corresponding column name for the database store.
	//
	// Available since v0.5.0
	ToDbColName(storageId, fieldName string) string

	// ToBoFieldName maps a database store's column name to the corresponding IGenericBo field name.
	//
	// Available since v0.5.0
	ToBoFieldName(storageId, colName string) string
}

IRowMapper transforms a database row to IGenericBo and vice versa.

Available since v0.0.2

type SortingField

type SortingField struct {
	FieldName  string
	Descending bool
}

SortingField specifies sorting on a specific field.

Available since v0.5.0

func (*SortingField) ToSortingOpt

func (sf *SortingField) ToSortingOpt() *SortingOpt

ToSortingOpt is a helper function to convert this SortingField to SortingOpt.

type SortingOpt

type SortingOpt struct {
	Fields []*SortingField
}

SortingOpt captures the ordering spec when fetching rows from storage.

Available since v0.5.0

func (*SortingOpt) Add

func (so *SortingOpt) Add(fields ...*SortingField) *SortingOpt

Add appends fields to the sorting list.