henge

package module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 6, 2022 License: MIT Imports: 22 Imported by: 0

README

henge

Go Report Card PkgGoDev Actions Status codecov Release

An out-of-the-box NoSQL-style universal data access layer implementation for Go.

Documentation

henge aims to free application and developer from the headache of implementing low-level underlying data access layer (DAL) by offering a universal DAL implementation.

At a glance, henge can fit into application's data access layers as illustrated in the following diagram:

henge-design-full

Data storage layer

henge provides a ready-to-use data storage layer that supports (since v0.3.0):

  • Azure Cosmos DB
  • AWS DynamoDB
  • MongoDB
  • MySQL
  • MSSQL
  • PostgreSQL
  • Oracle
  • SQLite (for non-production only, i.e. testing, poc, demo)

henge uses the following schema for data storage layer (*):

  • Field/column zid: business object's unique id, implemented as primary key (for SQL storage) or partition key (for no-SQL storage). Its data type is VARCHAR or string (whichever is best fit with the underlying data store).
  • Field/column zdata: store business object's member values. Its data type is TEXT, CLOB, JSONB or string (whichever is best fit with the underlying data store).
  • Field/column zchecksum: checksum of business object data. Its data type is VARCHAR or string (whichever is best fit with the underlying data store).
  • Field/column ztcreated and ztupdated: timestamp when business object is created/last updated. Its data type is DATETIME, TIMESTAMP or string (whichever is best fit with the underlying data store).
  • Field/column ztversion: for application's internal use (can be used for compatibility check or data migration). Its data type is BIGINT, INT or number (whichever is best fit with the underlying data store).

(*) column names and data types may differ depends on the underlying data store.

henge also allows application to define its own fields/columns.

"Universal" Business Object (BO) and Data Access Object (DAO) implementations

henge also provides ready-to-use BO & DAO implementation to interact with the data storage layer.

(Optional) Custom Business Object (BO) and Data Access Object (DAO) implementations

Application can have its own BO and DAO implemenations. See source code of test scripts for examples.

License

MIT - see LICENSE.md.

Documentation

Overview

Package henge is an out-of-the-box NoSQL style universal data access layer implementation.

See project's wiki for documentation: https://github.com/btnguyen2k/henge/wiki

Index

Constants

View Source
const (
	// AwsDynamodbUidxTableSuffix holds prefix string of the secondary table which henge uses to manage unique indexes.
	AwsDynamodbUidxTableSuffix = "_uidx"

	// AwsDynamodbUidxTableColName holds name of the secondary table's column to store unique index name.
	AwsDynamodbUidxTableColName = "uname"

	// AwsDynamodbUidxTableColHash holds name of the secondary table's column to store unique index hash value.
	AwsDynamodbUidxTableColHash = "uhash"
)
View Source
const (
	// SqlColId is name of table column to store BO's id.
	SqlColId = "zid"
	// SqlColData is name of table column to store BO's user-defined attributes in JSON format.
	SqlColData = "zdata"
	// SqlColChecksum is name of table column to store checksum of BO's value.
	SqlColChecksum = "zchecksum"
	// SqlColTimeCreated is name of table column to store BO's creation timestamp.
	SqlColTimeCreated = "ztcreated"
	// SqlColTimeUpdated is name of table column to store BO's last-updated timestamp.
	SqlColTimeUpdated = "ztupdated"
	// SqlColTagVersion is name of table column to store BO's "tag-version" - a value that can be used for compatibility check or data migration.
	SqlColTagVersion = "ztversion"
)
View Source
const (
	// FieldId is a top level field: BO's unique id.
	FieldId = "id"

	// FieldData is a top level field: BO's user-defined attributes in JSON format.
	FieldData = "data"

	// FieldTagVersion is a top level field: BO's "tag-version" - a value that can be used for compatibility check or data migration.
	FieldTagVersion = "tver"

	// FieldChecksum is a top level field: checksum of BO's value.
	FieldChecksum = "csum"

	// FieldTimeCreated is a top level field: BO's creation timestamp.
	FieldTimeCreated = "tcre"

	// FieldTimeUpdated is a top level field: BO's last-updated timestamp.
	FieldTimeUpdated = "tupd"

	// FieldExtras is an internally used field.
	FieldExtras = "_ext"
)
View Source
const (
	// DefaultTimestampRoundingSetting is the default TimestampRoundingSetting to be used if such setting is not specified.
	//
	// Available since v0.5.4
	DefaultTimestampRoundingSetting = TimestampRoundingSettingSecond

	// DefaultTimeLayout is the default layout used by UniversalBo to convert datetime values to string and vice versa if such setting is not specified.
	//
	// Available since v0.5.4
	DefaultTimeLayout = time.RFC3339Nano
)
View Source
const (
	// CosmosdbColId holds the name of CosmosDB collection's "id" field.
	CosmosdbColId = FieldId // since CosmosDB is schemaless, name of "id" field can be the same as name ò "id" db column
)
View Source
const (
	// MongoColId holds the name of MongoDB collection's "id" field.
	MongoColId = "_id"
)
View Source
const (
	// Version of package henge.
	Version = "0.6.0"
)

Variables

This section is empty.

Functions

func CreateIndexSql

func CreateIndexSql(sqlc *prom.SqlConnect, tableName string, unique bool, cols []string) error

CreateIndexSql generates and executes "CREATE INDEX" SQL statement.

func CreateTableSql

func CreateTableSql(sqlc *prom.SqlConnect, tableName string, ifNotExist bool, colDef map[string]string, colNames, pk []string) error

CreateTableSql generates and executes "CREATE TABLE" SQL statement.

  • if ifNotExist is true the SQL statement will be generated as CREATE TABLE IF NOT EXISTS table-name...
  • colDef is a map of {table-col-name:col-type} and must

func InitCosmosdbCollection added in v0.3.0

func InitCosmosdbCollection(sqlc *prom.SqlConnect, tableName string, spec *CosmosdbCollectionSpec) error

InitCosmosdbCollection initializes a database collection to store henge business objects.

Collection is created with "IF NOT EXISTS".

Available: since v0.3.2

func InitDynamodbTables added in v0.3.0

func InitDynamodbTables(adc *prom.AwsDynamodbConnect, tableName string, spec *DynamodbTablesSpec) error

InitDynamodbTables initializes a DynamoDB table(s) to store henge business objects.

  • The main table to store business objects.
  • The secondary table is used to manage unique indexes. The secondary table has the same base name and suffixed by AwsDynamodbUidxTableSuffix.
  • The secondary table has the following schema: { AwsDynamodbUidxTableColName, AwsDynamodbUidxTableColHash }
  • Other than the two tables, no local index or global index is created.
  • (since v0.3.2) spec.MainTableCustomAttrs can be used to define main table's custom attributes.
  • (since v0.3.2) spec.MainTablePkPrefix can be used to override main table's PK.
  • if spec.MainTablePkPrefix is not supplied, main table is created with PK as { FieldId }
  • otherwise, main table is created with PK as { spec.MainTablePkPrefix, FieldId }

Available: since v0.3.0

func InitMongoCollection

func InitMongoCollection(mc *prom.MongoConnect, collectionName string) error

InitMongoCollection initializes a MongoDB collection to store henge business objects.

  • This function creates the specified collection with default settings.
  • Other than the collection, no index is created.

func InitMssqlTable

func InitMssqlTable(sqlc *prom.SqlConnect, tableName string, extraCols map[string]string) error

InitMssqlTable initializes a database table to store henge business objects.

  • Table is created as the following: { SqlColId: "NVARCHAR(64)", SqlColData: "NTEXT", SqlColChecksum: "NVARCHAR(32)", SqlColTimeCreated: "DATETIMEOFFSET", SqlColTimeUpdated: "DATETIMEOFFSET", SqlColTagVersion: "BIGINT" }, plus additional column defined by extraCols parameter.
  • This function returns error if the table already existed.
  • SqlColId is table's primary key.
  • extraCols (nillable) is a map of {col-name:col-type} and is supplied so that table columns other than core columns are also created.
  • extraCols can also be used to override data type of core columns.
  • Other than the database table, no index is created.

func InitMysqlTable

func InitMysqlTable(sqlc *prom.SqlConnect, tableName string, extraCols map[string]string) error

InitMysqlTable initializes a database table to store henge business objects.

  • Table is created "if not exists" as the following: { SqlColId: "VARCHAR(64)", SqlColData: "TEXT", SqlColChecksum: "VARCHAR(32)", SqlColTimeCreated: "TIMESTAMP DEFAULT CURRENT_TIMESTAMP", SqlColTimeUpdated: "TIMESTAMP DEFAULT CURRENT_TIMESTAMP", SqlColTagVersion: "BIGINT" }, plus additional column defined by extraCols parameter.
  • SqlColId is table's primary key.
  • extraCols (nillable) is a map of {col-name:col-type} and is supplied so that table columns other than core columns are also created.
  • extraCols can also be used to override data type of core columns.
  • Other than the database table, no index is created.

func InitOracleTable

func InitOracleTable(sqlc *prom.SqlConnect, tableName string, extraCols map[string]string) error

InitOracleTable initializes a database table to store henge business objects.

  • Table is created "if not exists" as the following: { SqlColId: "NVARCHAR2(64)", SqlColData: "CLOB", SqlColChecksum: "NVARCHAR2(32)", SqlColTimeCreated: "TIMESTAMP WITH TIME ZONE", SqlColTimeUpdated: "TIMESTAMP WITH TIME ZONE", SqlColTagVersion: "INT" }, plus additional column defined by extraCols parameter.
  • SqlColId is table's primary key.
  • extraCols (nillable) is a map of {col-name:col-type} and is supplied so that table columns other than core columns are also created.
  • extraCols can also be used to override data type of core columns.
  • Other than the database table, no index is created.

func InitPgsqlTable

func InitPgsqlTable(sqlc *prom.SqlConnect, tableName string, extraCols map[string]string) error

InitPgsqlTable initializes a database table to store henge business objects.

  • Table is created "if not exists" as the following: { SqlColId: "VARCHAR(64)", SqlColData: "JSONB", SqlColChecksum: "VARCHAR(32)", SqlColTimeCreated: "TIMESTAMP WITH TIME ZONE", SqlColTimeUpdated: "TIMESTAMP WITH TIME ZONE", SqlColTagVersion: "BIGINT" }, plus additional column defined by extraCols parameter.
  • SqlColId is table's primary key.
  • extraCols (nillable) is a map of {col-name:col-type} and is supplied so that table columns other than core columns are also created.
  • extraCols can also be used to override data type of core columns.
  • Other than the database table, no index is created.

func InitSqliteTable

func InitSqliteTable(sqlc *prom.SqlConnect, tableName string, extraCols map[string]string) error

InitSqliteTable initializes a database table to store henge business objects.

  • Table is created "if not exists" as the following: { SqlColId: "VARCHAR(64)", SqlColData: "TEXT", SqlColChecksum: "VARCHAR(32)", SqlColTimeCreated: "TIMESTAMP", SqlColTimeUpdated: "TIMESTAMP", SqlColTagVersion: "BIGINT" }, plus additional column defined by extraCols parameter.
  • SqlColId is table's primary key.
  • extraCols (nillable) is a map of {col-name:col-type} and is supplied so that table columns other than core columns are also created.
  • extraCols can also be used to override data type of core columns.
  • Other than the database table, no index is created.

func NewCosmosdbConnection added in v0.3.0

func NewCosmosdbConnection(url, timezone, driver string, defaultTimeoutMs int, poolOptions *prom.SqlPoolOptions) (*prom.SqlConnect, error)

NewCosmosdbConnection is helper function to create connection pools for Azure Cosmos DB using database/sql interface.

Note: it's application's responsibility to import proper Azure Cosmos DB driver, e.g. import _ "github.com/btnguyen2k/gocosmos" and supply the correct driver, e.g. "gocosmos".

Available: since v0.3.0

func NewMssqlConnection

func NewMssqlConnection(url, timezone, driver string, defaultTimeoutMs int, poolOptions *prom.SqlPoolOptions) (*prom.SqlConnect, error)

NewMssqlConnection is helper function to create connection pools for MSSQL.

Note: it's application's responsibility to import proper MSSQL driver, e.g. import _ "github.com/denisenkom/go-mssqldb" and supply the correct driver, e.g. "sqlserver".

func NewMysqlConnection

func NewMysqlConnection(url, timezone, driver string, defaultTimeoutMs int, poolOptions *prom.SqlPoolOptions) (*prom.SqlConnect, error)

NewMysqlConnection is helper function to create connection pools for MySQL.

Note: it's application's responsibility to import proper MySQL driver, e.g. import _ "github.com/go-sql-driver/mysql" and supply the correct driver, e.g. "mysql".

func NewOracleConnection

func NewOracleConnection(url, timezone, driver string, defaultTimeoutMs int, poolOptions *prom.SqlPoolOptions) (*prom.SqlConnect, error)

NewOracleConnection is helper function to create connection pools for Oracle.

Note: it's application's responsibility to import proper Oracle driver, e.g. import _ "github.com/godror/godror" and supply the correct driver, e.g. "godror".

func NewPgsqlConnection

func NewPgsqlConnection(url, timezone, driver string, defaultTimeoutMs int, poolOptions *prom.SqlPoolOptions) (*prom.SqlConnect, error)

NewPgsqlConnection is helper function to create connection pools for PostgreSQL.

Note: it's application's responsibility to import proper PostgreSQL driver, e.g. import _ "github.com/jackc/pgx/v4/stdlib" and supply the correct driver, e.g. "pgx".

func NewSqlConnection added in v0.3.0

func NewSqlConnection(url, timezone, driver string, dbFlavor prom.DbFlavor, defaultTimeoutMs int, poolOptions *prom.SqlPoolOptions) (*prom.SqlConnect, error)

NewSqlConnection is convenient function to create prom.SqlConnect instance.

Note: it's application's responsibility to import proper SQL driver and supply the correct driver.

Note: timezone is default to UTC if not supplied.

Available: since v0.3.0

func NewSqliteConnection

func NewSqliteConnection(dir, dbName, timezone, driver string, defaultTimeoutMs int, poolOptions *prom.SqlPoolOptions) (*prom.SqlConnect, error)

NewSqliteConnection is helper function to create connection pools for SQLite.

  • dir is the root directory to store SQLite data files.
  • dbName is name of the SQLite database.

Note: it's application's responsibility to import proper sqlite driver, e.g. import _ "github.com/mattn/go-sqlite3" and supply the correct driver, e.g. "sqlite3".

Types

type CosmosdbCollectionSpec added in v0.3.2

type CosmosdbCollectionSpec struct {
	Ru, MaxRu   int        // collection's RU/MAXRU setting
	Pk, LargePk string     // collection's PK or Large-PK name
	Uk          [][]string // collection's unique key settings
}

CosmosdbCollectionSpec holds specification of CosmosDB collection to be created.

Available: since v0.3.2

type CosmosdbDaoSpec added in v0.3.2

type CosmosdbDaoSpec struct {
	PkName        string // (multi-tenant) name of collection's PK attribute
	PkValue       string // (multi-tenant) static value for PkName attribute
	TxModeOnWrite bool   // for compatibility only, not used.
}

CosmosdbDaoSpec holds specification of UniversalDaoCosmosdb to be created.

Available: since v0.3.2

type DynamodbDaoSpec added in v0.3.2

type DynamodbDaoSpec struct {
	PkPrefix      string     // (multi-tenant) if pkPrefix is supplied, table's PK is { PkPrefix, FieldId }, otherwise table's PK is { FieldId }
	PkPrefixValue string     // (multi-tenant) static value for PkPrefix attribute
	UidxAttrs     [][]string // list of unique indexes, each unique index is a combination of table columns
}

DynamodbDaoSpec holds specification of UniversalDaoDynamodb to be created.

Available: since v0.3.2

type DynamodbTablesSpec added in v0.3.2

type DynamodbTablesSpec struct {
	MainTableRcu         int64                         // rcu of the main table
	MainTableWcu         int64                         // wcu of the main table
	MainTableCustomAttrs []prom.AwsDynamodbNameAndType // main table's custom attributes (beside henge's attributes)
	MainTablePkPrefix    string                        // prefix attribute to main table's PK (if defined, PK of the main table is { pkPrefix, FieldId }; otherwise { FieldId } ). MainTablePkPrefix, if specified, must be included in MainTableCustomAttrs.
	CreateUidxTable      bool                          // if true, the secondary table is created
	UidxTableRcu         int64                         // rcu of the secondary table
	UidxTableWcu         int64                         // wcu of the secondary table
}

DynamodbTablesSpec holds specification of DynamoDB tables to be created.

Available: since v0.3.2

type FuncFilterGeneratorSql added in v0.3.0

type FuncFilterGeneratorSql func(tableName string, input interface{}) godal.FilterOpt

FuncFilterGeneratorSql defines an API to generate filter for universal BO, to be used with UniversalDaoSql.

input can be either UniversalBo, *UniversalBo, godal.IGenericBo or godal.FilterOpt instance.

Available: since v0.3.0

type FuncPostUboToMap

type FuncPostUboToMap func(map[string]interface{}) map[string]interface{}

FuncPostUboToMap is used by UniversalBo.ToMap to transform the result map (output from FuncPreUboToMap) to another map[string]interface{}.

type FuncPreUboToMap

type FuncPreUboToMap func(*UniversalBo) map[string]interface{}

FuncPreUboToMap is used by UniversalBo.ToMap to export UniversalBo's attributes to a map[string]interface{}.

var DefaultFuncPreUboToMap FuncPreUboToMap = func(_ubo *UniversalBo) map[string]interface{} {
	ubo := _ubo.Clone()
	return map[string]interface{}{
		FieldId:          ubo.id,
		FieldData:        ubo.dataJson,
		FieldTagVersion:  ubo.tagVersion,
		FieldChecksum:    ubo.checksum,
		FieldTimeCreated: ubo.timeCreated,
		FieldTimeUpdated: ubo.timeUpdated,
		FieldExtras:      cloneMap(ubo._extraAttrs),
	}
}

DefaultFuncPreUboToMap is default implementation of FuncPreUboToMap.

This function exports the input UniversalBo as-is to a map with following fields: { FieldId (string), FieldData (string), FieldTagVersion (uint64), FieldChecksum (string), FieldTimeCreated (time.Time), FieldTimeUpdated (time.Time), FieldExtras (map[string]interface{}) }

type TimestampRoundingSetting added in v0.5.6

type TimestampRoundingSetting int

TimestampRoundingSetting specifies how UniversalBo would round timestamp before storing.

Available since v0.4.0 (renamed to TimestampRoundingSetting since v0.5.6)

const (
	// TimestampRoundingSettingNone specifies that timestamp is not rounded.
	TimestampRoundingSettingNone TimestampRoundingSetting = iota

	// TimestampRoundingSettingNanosecond specifies that timestamp is rounded to nanosecond.
	TimestampRoundingSettingNanosecond

	// TimestampRoundingSettingMicrosecond specifies that timestamp is rounded to microsecond.
	TimestampRoundingSettingMicrosecond

	// TimestampRoundingSettingMillisecond specifies that timestamp is rounded to millisecond.
	TimestampRoundingSettingMillisecond

	// TimestampRoundingSettingSecond specifies that timestamp is rounded to second.
	TimestampRoundingSettingSecond
)

type UboOpt added in v0.5.4

type UboOpt struct {
	TimeLayout        string
	TimestampRounding TimestampRoundingSetting
}

UboOpt can be supplied to NewUniversalBo and NewUniversalBoFromGbo to specify newly created BO's settings.

Available since v0.5.4

type UboSyncOpts added in v0.5.3

type UboSyncOpts struct {
	UpdateTimestamp                 bool // if true, UniversalBo's last-updated timestamp is updated with the current timestamp
	UpdateTimestampIfChecksumChange bool // if true, UniversalBo's last-updated timestamp is updated with the current timestamp if BO's checksum changes
}

UboSyncOpts specifies behaviors of UniversalBo.Sync function.

Available since v0.5.3

type UniversalBo

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

UniversalBo is the NoSQL style universal business object. Business attributes are stored in a JSON-encoded attribute.

func NewUniversalBo

func NewUniversalBo(id string, tagVersion uint64, opts ...UboOpt) *UniversalBo

NewUniversalBo is helper function to create a new UniversalBo instance.

Note: id will be space-trimmed.

func NewUniversalBoFromGbo added in v0.4.1

func NewUniversalBoFromGbo(gbo godal.IGenericBo, opts ...UboOpt) *UniversalBo

NewUniversalBoFromGbo is helper function to construct a new UniversalBo from transforms godal.IGenericBo.

Available since v0.4.1

func (*UniversalBo) Clone

func (ubo *UniversalBo) Clone() *UniversalBo

Clone creates a cloned copy of the business object.

func (*UniversalBo) GetChecksum

func (ubo *UniversalBo) GetChecksum() string

GetChecksum returns value of bo's 'checksum' field.

func (*UniversalBo) GetDataAttr

func (ubo *UniversalBo) GetDataAttr(path string) (interface{}, error)

GetDataAttr is alias of GetDataAttrAs(path, nil).

func (*UniversalBo) GetDataAttrAs

func (ubo *UniversalBo) GetDataAttrAs(path string, typ reflect.Type) (interface{}, error)

GetDataAttrAs returns value, converted to the specified type, of a data attribute located at 'path'.

func (*UniversalBo) GetDataAttrAsTimeWithLayout

func (ubo *UniversalBo) GetDataAttrAsTimeWithLayout(path, layout string) (time.Time, error)

GetDataAttrAsTimeWithLayout returns value, converted to time, of a data attribute located at 'path'.

func (*UniversalBo) GetDataAttrAsTimeWithLayoutUnsafe

func (ubo *UniversalBo) GetDataAttrAsTimeWithLayoutUnsafe(path, layout string) time.Time

GetDataAttrAsTimeWithLayoutUnsafe is similar to GetDataAttrAsTimeWithLayout but ignoring error.

func (*UniversalBo) GetDataAttrAsUnsafe

func (ubo *UniversalBo) GetDataAttrAsUnsafe(path string, typ reflect.Type) interface{}

GetDataAttrAsUnsafe is similar to GetDataAttrAs but ignoring error.

func (*UniversalBo) GetDataAttrUnsafe

func (ubo *UniversalBo) GetDataAttrUnsafe(path string) interface{}

GetDataAttrUnsafe is similar to GetDataAttr but ignoring error.

func (*UniversalBo) GetDataJson

func (ubo *UniversalBo) GetDataJson() string

GetDataJson returns bo's user-defined attributes in JSON format.

func (*UniversalBo) GetExtraAttr

func (ubo *UniversalBo) GetExtraAttr(key string) interface{}

GetExtraAttr returns value of an 'extra' attribute specified by 'key'.

func (*UniversalBo) GetExtraAttrAs

func (ubo *UniversalBo) GetExtraAttrAs(key string, typ reflect.Type) (interface{}, error)

GetExtraAttrAs returns value, converted to the specified type, of an 'extra' attribute specified by 'key'.

func (*UniversalBo) GetExtraAttrAsTimeWithLayout

func (ubo *UniversalBo) GetExtraAttrAsTimeWithLayout(key, layout string) (time.Time, error)

GetExtraAttrAsTimeWithLayout returns value, converted to time, of an 'extra' attribute specified by 'key'.

func (*UniversalBo) GetExtraAttrAsTimeWithLayoutUnsafe

func (ubo *UniversalBo) GetExtraAttrAsTimeWithLayoutUnsafe(key, layout string) time.Time

GetExtraAttrAsTimeWithLayoutUnsafe is similar to GetExtraAttrAsTimeWithLayout but no error is returned.

func (*UniversalBo) GetExtraAttrAsUnsafe

func (ubo *UniversalBo) GetExtraAttrAsUnsafe(key string, typ reflect.Type) interface{}

GetExtraAttrAsUnsafe is similar to GetExtraAttrAs but no error is returned.

func (*UniversalBo) GetExtraAttrs

func (ubo *UniversalBo) GetExtraAttrs() map[string]interface{}

GetExtraAttrs returns the 'extra-attrs' map.

func (*UniversalBo) GetId

func (ubo *UniversalBo) GetId() string

GetId returns value of bo's 'id' field.

func (*UniversalBo) GetTagVersion

func (ubo *UniversalBo) GetTagVersion() uint64

GetTagVersion returns value of bo's 'tag-version' field.

func (*UniversalBo) GetTimeCreated

func (ubo *UniversalBo) GetTimeCreated() time.Time

GetTimeCreated returns value of bo's 'timestamp-created' field.

func (*UniversalBo) GetTimeUpdated

func (ubo *UniversalBo) GetTimeUpdated() time.Time

GetTimeUpdated returns value of bo's 'timestamp-updated' field.

func (*UniversalBo) GetTimestampRounding added in v0.5.4

func (ubo *UniversalBo) GetTimestampRounding() TimestampRoundingSetting

GetTimestampRounding returns this BO's timestamp-rounding setting. Timestamp-rounding controls how BO's create/update timestamp will be rounded before storing.

Available since v0.5.4

func (*UniversalBo) IsDirty

func (ubo *UniversalBo) IsDirty() bool

IsDirty returns 'true' if bo's data has been modified.

func (*UniversalBo) MarshalJSON

func (ubo *UniversalBo) MarshalJSON() ([]byte, error)

MarshalJSON implements json.encode.Marshaler.MarshalJSON.

func (*UniversalBo) NormalizeTimestampForStoring added in v0.5.6

func (ubo *UniversalBo) NormalizeTimestampForStoring(t time.Time, layout string) string

NormalizeTimestampForStoring normalizes the input time for storing.

  • Firstly, the input time is rounded according to bo's timestamp-rounding setting.
  • Then, the rounded time is converted to string according to the specified layout.

Available since v0.5.6

func (*UniversalBo) RoundTimestamp added in v0.5.6

func (ubo *UniversalBo) RoundTimestamp(t time.Time) time.Time

RoundTimestamp rounds the input time according to bo's timestamp-rounding setting and returns the result.

Available since v0.5.6

func (*UniversalBo) SetDataAttr

func (ubo *UniversalBo) SetDataAttr(path string, value interface{}) error

SetDataAttr sets value of a data attribute located at 'path'.

- If value is a time.Time (or *time.Time), the time value is rounded according to the BO's timestamp-rounding setting. - (since v0.5.5) Furthermore, the time value is converted to string (using layout DefaultTimeLayout) before storing.

func (*UniversalBo) SetDataJson

func (ubo *UniversalBo) SetDataJson(value string) *UniversalBo

SetDataJson sets bo's user-defined attributes as a whole in JSON format.

func (*UniversalBo) SetExtraAttr

func (ubo *UniversalBo) SetExtraAttr(key string, value interface{}) *UniversalBo

SetExtraAttr sets value of an 'extra' attribute specified by 'key'.

- If value is a time.Time (or *time.Time), the time value is rounded according to the BO's timestamp-rounding setting.

func (*UniversalBo) SetId

func (ubo *UniversalBo) SetId(value string) *UniversalBo

SetId sets value of bo's 'id' field.

func (*UniversalBo) SetTagVersion

func (ubo *UniversalBo) SetTagVersion(value uint64) *UniversalBo

SetTagVersion sets value of bo's 'tag-version' field.

func (*UniversalBo) SetTimeUpdated

func (ubo *UniversalBo) SetTimeUpdated(value time.Time) *UniversalBo

SetTimeUpdated sets value of bo's 'timestamp-updated' field.

func (*UniversalBo) SetTimestampRounding added in v0.5.4

func (ubo *UniversalBo) SetTimestampRounding(value TimestampRoundingSetting) *UniversalBo

SetTimestampRounding updates this BO's timestamp-rounding setting. Timestamp-rounding controls how BO's create/update timestamp will be rounded before storing.

Available since v0.5.4

func (*UniversalBo) Sync

func (ubo *UniversalBo) Sync(opts ...UboSyncOpts) *UniversalBo

Sync syncs user-defined attribute values to JSON format.

func (*UniversalBo) ToGenericBo added in v0.4.1

func (ubo *UniversalBo) ToGenericBo() godal.IGenericBo

ToGenericBo exports the BO data to a godal.IGenericBo.

  • the exported godal.IGenericBo is populated with fields FieldId, FieldData, FieldChecksum, FieldTimeCreated, FieldTimeUpdated and FieldTagVersion.

Available since v0.4.1

func (*UniversalBo) ToMap

func (ubo *UniversalBo) ToMap(preFunc FuncPreUboToMap, postFunc FuncPostUboToMap) map[string]interface{}

ToMap exports the BO data to a map[string]interface{}.

  • preFunc is used to export BO data to a map. If not supplied, DefaultFuncPreUboToMap is used.
  • postFunc is used to transform the result map (output from preFunc) to the final result. If not supplied, the result from preFunc is returned as-is.

func (*UniversalBo) UnmarshalJSON

func (ubo *UniversalBo) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.decode.Unmarshaler.UnmarshalJSON.

type UniversalDao

type UniversalDao interface {
	// ToUniversalBo transforms godal.IGenericBo to business object.
	ToUniversalBo(gbo godal.IGenericBo) *UniversalBo

	// ToGenericBo transforms the business object to godal.IGenericBo.
	ToGenericBo(ubo *UniversalBo) godal.IGenericBo

	// Delete removes the specified business object from storage.
	// This function returns true if number of deleted records is non-zero.
	Delete(bo *UniversalBo) (bool, error)

	// Create persists a new business object to storage.
	// This function returns true if number of inserted records is non-zero.
	Create(bo *UniversalBo) (bool, error)

	// Get retrieves a business object from storage.
	Get(id string) (*UniversalBo, error)

	// GetN retrieves N business objects from storage.
	GetN(fromOffset, maxNumRows int, filter godal.FilterOpt, sorting *godal.SortingOpt) ([]*UniversalBo, error)

	// GetAll retrieves all available business objects from storage.
	GetAll(filter godal.FilterOpt, sorting *godal.SortingOpt) ([]*UniversalBo, error)

	// Update modifies an existing business object.
	// This function returns true if number of updated records is non-zero.
	Update(bo *UniversalBo) (bool, error)

	// Save creates new business object or updates an existing one.
	// This function returns the existing record along with value true if number of inserted/updated record is non-zero.
	Save(bo *UniversalBo) (bool, *UniversalBo, error)
}

UniversalDao defines API to access UniversalBo storage.

func NewUniversalDaoCosmosdbSql added in v0.3.0

func NewUniversalDaoCosmosdbSql(sqlc *prom.SqlConnect, tableName string, spec *CosmosdbDaoSpec) UniversalDao

NewUniversalDaoCosmosdbSql is helper method to create UniversalDaoSql instance specific for Azure Cosmos DB.

  • txModeOnWrite: added for compatibility,not used.

Available: since v0.3.0

func NewUniversalDaoMongo

func NewUniversalDaoMongo(mc *prom.MongoConnect, collectionName string, txModeOnWrite bool, defaultUboOpts ...UboOpt) UniversalDao

NewUniversalDaoMongo is helper method to create UniversalDaoMongo instance.

  • txModeOnWrite: enables/disables transaction mode on write operations. MongoDB's implementation of GdaoCreate is "get/check and write". It can be done either in transaction (txModeOnWrite=true) or non-transaction (txModeOnWrite=false) mode. As of MongoDB 4.0, transactions are available for replica set deployments only. Since MongoDB 4.2, transactions are also available for sharded cluster. It is recommended to set "txModeOnWrite=true" whenever possible.
  • defaultUboOpts: (since v0.5.7) the default options to be used by the DAO when creating UniversalBo instances.

func NewUniversalDaoSql

func NewUniversalDaoSql(sqlc *prom.SqlConnect, tableName string, txModeOnWrite bool,
	extraColNameToFieldMappings map[string]string, defaultUboOpts ...UboOpt) UniversalDao

NewUniversalDaoSql is helper method to create UniversalDaoSql instance.

  • txModeOnWrite: enables/disables transaction mode on write operations. RDBMS/SQL's implementation of GdaoSave is "try update, if failed then insert". It can be done either in transaction (txModeOnWrite=true) or non-transaction (txModeOnWrite=false) mode. Recommended setting is "txModeOnWrite=true".
  • defaultUboOpts: (since v0.5.7) the default options to be used by the DAO when creating UniversalBo instances.

type UniversalDaoCosmosdbSql added in v0.3.2

type UniversalDaoCosmosdbSql struct {
	*UniversalDaoSql
	// contains filtered or unexported fields
}

UniversalDaoCosmosdbSql is CosmosDB-based (using driver/sql interface) implementation of UniversalDao.

Available: since v0.3.2

func (*UniversalDaoCosmosdbSql) Get added in v0.3.2

Get implements UniversalDao.Get.

func (*UniversalDaoCosmosdbSql) GetAll added in v0.3.2

func (dao *UniversalDaoCosmosdbSql) GetAll(filter godal.FilterOpt, sorting *godal.SortingOpt) ([]*UniversalBo, error)

GetAll implements UniversalDao.GetAll.

func (*UniversalDaoCosmosdbSql) GetN added in v0.3.2

func (dao *UniversalDaoCosmosdbSql) GetN(fromOffset, maxNumRows int, filter godal.FilterOpt, sorting *godal.SortingOpt) ([]*UniversalBo, error)

GetN implements UniversalDao.GetN.

func (*UniversalDaoCosmosdbSql) GetPkName added in v0.3.2

func (dao *UniversalDaoCosmosdbSql) GetPkName() string

GetPkName returns attribute name of collection's PK.

func (*UniversalDaoCosmosdbSql) GetPkValue added in v0.3.2

func (dao *UniversalDaoCosmosdbSql) GetPkValue() string

GetPkValue returns static value of collection's PK.

func (*UniversalDaoCosmosdbSql) Save added in v0.3.2

Save implements UniversalDao.Save.

func (*UniversalDaoCosmosdbSql) ToUniversalBo added in v0.4.1

func (dao *UniversalDaoCosmosdbSql) ToUniversalBo(gbo godal.IGenericBo) *UniversalBo

ToUniversalBo transforms godal.IGenericBo to business object.

type UniversalDaoDynamodb

type UniversalDaoDynamodb struct {
	*dynamodb.GenericDaoDynamodb
	// contains filtered or unexported fields
}

UniversalDaoDynamodb is AWS DynamoDB-based implementation of UniversalDao.

func NewUniversalDaoDynamodb

func NewUniversalDaoDynamodb(adc *prom.AwsDynamodbConnect, tableName string, spec *DynamodbDaoSpec, defaultUboOpts ...UboOpt) *UniversalDaoDynamodb

NewUniversalDaoDynamodb is helper method to create UniversalDaoDynamodb instance.

  • uidxAttrs list of unique indexes, each unique index is a combination of table columns.
  • the table has default pk as { FieldId }. If pkPrefix is supplied, table pk becomes { pkPrefix, FieldId }.
  • static value for pkPrefix attribute can be specified via pkPrefixValue.
  • defaultUboOpts: (since v0.5.7) the default options to be used by the DAO when creating UniversalBo instances.

func (*UniversalDaoDynamodb) BuildUidxValues

func (dao *UniversalDaoDynamodb) BuildUidxValues(bo godal.IGenericBo) map[string]string

BuildUidxValues calculate unique index hash value from a godal.IGenericBo.

The return value is a map {uidxName:uidxHashValue}.

func (*UniversalDaoDynamodb) Create

func (dao *UniversalDaoDynamodb) Create(bo *UniversalBo) (bool, error)

Create implements UniversalDao.Create.

func (*UniversalDaoDynamodb) Delete

func (dao *UniversalDaoDynamodb) Delete(bo *UniversalBo) (bool, error)

Delete implements UniversalDao.Delete.

func (*UniversalDaoDynamodb) GdaoCreateFilter

func (dao *UniversalDaoDynamodb) GdaoCreateFilter(_ string, bo godal.IGenericBo) godal.FilterOpt

GdaoCreateFilter implements IGenericDao.GdaoCreateFilter.

If dao.pkPrefix is specified, this function creates filter on compound PK as { dao.pkPrefix, FieldId }. Otherwise, filter on single-attribute PK as { FieldId } is created.

If dao.pkPrefix is specified, this function first fetches value of attribute dao.pkPrefix from BO. If the fetched value is empty, dao.pkPrefixValue is used.

func (*UniversalDaoDynamodb) Get

func (dao *UniversalDaoDynamodb) Get(id string) (*UniversalBo, error)

Get implements UniversalDao.Get.

func (*UniversalDaoDynamodb) GetAll

func (dao *UniversalDaoDynamodb) GetAll(filter godal.FilterOpt, sorting *godal.SortingOpt) ([]*UniversalBo, error)

GetAll implements UniversalDao.GetAll.

Currently, AWS DynamoDB does not support custom sorting. Since v0.5.2, UniversalDaoDynamodb allows limited sorting via GSI. See function GetN for more information.

func (*UniversalDaoDynamodb) GetDefaultUboOpts added in v0.5.7

func (dao *UniversalDaoDynamodb) GetDefaultUboOpts() []UboOpt

GetDefaultUboOpts returns the default options to be used by the DAO when creating UniversalBo instances.

Available since v0.5.7

func (*UniversalDaoDynamodb) GetN

func (dao *UniversalDaoDynamodb) GetN(fromOffset, maxNumRows int, filter godal.FilterOpt, sorting *godal.SortingOpt) ([]*UniversalBo, error)

GetN implements UniversalDao.GetN.

Currently, AWS DynamoDB does not support custom sorting. Since v0.5.2, UniversalDaoDynamodb allows limited sorting via GSI:

  • Once sorting parameter is specified, this function looks up GSI name from field names (see function MapGsi).
  • If GSI name is found, data will be queried using the GSI.

Note: Only ascending order is supported, also it's responsibility of application to:

  • Create GSIs.
  • Map fields to GSI by calling function MapGsi.
  • Supply appropriate filter.

func (*UniversalDaoDynamodb) GetPkPrefix added in v0.3.2

func (dao *UniversalDaoDynamodb) GetPkPrefix() string

GetPkPrefix returns value of dao.pkPrefix.

pkPrefix and pkPrefix are used by GdaoCreateFilter.

Available: since v0.3.2

func (*UniversalDaoDynamodb) GetPkPrefixValue added in v0.3.2

func (dao *UniversalDaoDynamodb) GetPkPrefixValue() string

GetPkPrefixValue returns static value for dao.pkPrefix attribute.

pkPrefix and pkPrefix are used by GdaoCreateFilter.

Available: since v0.3.2

func (*UniversalDaoDynamodb) GetTableName

func (dao *UniversalDaoDynamodb) GetTableName() string

GetTableName returns name of database table to store business objects.

func (*UniversalDaoDynamodb) GetUidxAttrs

func (dao *UniversalDaoDynamodb) GetUidxAttrs() [][]string

GetUidxAttrs returns list of unique indexes (each unique index is a combination of table columns).

func (*UniversalDaoDynamodb) GetUidxHashFunctions

func (dao *UniversalDaoDynamodb) GetUidxHashFunctions() []checksum.HashFunc

GetUidxHashFunctions returns the hash functions used to calculate unique index hash.

Currently two hash functions are used.

func (*UniversalDaoDynamodb) GetUidxTableName

func (dao *UniversalDaoDynamodb) GetUidxTableName() string

GetUidxTableName returns name of database table to store unique indexes.

func (*UniversalDaoDynamodb) Init added in v0.5.7

func (dao *UniversalDaoDynamodb) Init() error

Init should be called to initialize the DAO instance before use.

Available since v0.5.7

func (*UniversalDaoDynamodb) MapGsi added in v0.5.2

func (dao *UniversalDaoDynamodb) MapGsi(gsiName string, fieldNames ...string) *UniversalDaoDynamodb

MapGsi associates a list of table fields (in order) with a GSI. The mappings are to be used for sorting.

See function GetN for more information.

Available: since v0.5.2

func (*UniversalDaoDynamodb) Save

Save implements UniversalDao.Save.

func (*UniversalDaoDynamodb) SetDefaultUboOpts added in v0.5.7

func (dao *UniversalDaoDynamodb) SetDefaultUboOpts(uboOpts []UboOpt) *UniversalDaoDynamodb

SetDefaultUboOpts sets the default options to be used by the DAO when creating UniversalBo instances.

Available since v0.5.7

func (*UniversalDaoDynamodb) SetUidxAttrs

func (dao *UniversalDaoDynamodb) SetUidxAttrs(uidxAttrs [][]string) *UniversalDaoDynamodb

SetUidxAttrs sets unique indexes (each unique index is a combination of table columns).

func (*UniversalDaoDynamodb) SetUidxHashFunctions

func (dao *UniversalDaoDynamodb) SetUidxHashFunctions(uidxHashFuncs []checksum.HashFunc) *UniversalDaoDynamodb

SetUidxHashFunctions configures the hash functions used to calculate unique index hash.

Currently two hash functions are used, and two must be different. By default, the following hash functions will be used: checksum.Sha1HashFunc and checksum.Md5HashFunc

func (*UniversalDaoDynamodb) ToGenericBo

func (dao *UniversalDaoDynamodb) ToGenericBo(ubo *UniversalBo) godal.IGenericBo

ToGenericBo transforms business object to godal.IGenericBo.

func (*UniversalDaoDynamodb) ToUniversalBo

func (dao *UniversalDaoDynamodb) ToUniversalBo(gbo godal.IGenericBo) *UniversalBo

ToUniversalBo transforms godal.IGenericBo to business object.

func (*UniversalDaoDynamodb) Update

func (dao *UniversalDaoDynamodb) Update(bo *UniversalBo) (bool, error)

Update implements UniversalDao.Update.

type UniversalDaoMongo

type UniversalDaoMongo struct {
	*mongo.GenericDaoMongo
	// contains filtered or unexported fields
}

UniversalDaoMongo is MongoDB-based implementation of UniversalDao.

func (*UniversalDaoMongo) Create

func (dao *UniversalDaoMongo) Create(bo *UniversalBo) (bool, error)

Create implements UniversalDao.Create.

func (*UniversalDaoMongo) Delete

func (dao *UniversalDaoMongo) Delete(bo *UniversalBo) (bool, error)

Delete implements UniversalDao.Delete.

func (*UniversalDaoMongo) GdaoCreateFilter

func (dao *UniversalDaoMongo) GdaoCreateFilter(_ string, bo godal.IGenericBo) godal.FilterOpt

GdaoCreateFilter implements IGenericDao.GdaoCreateFilter.

func (*UniversalDaoMongo) Get

func (dao *UniversalDaoMongo) Get(id string) (*UniversalBo, error)

Get implements UniversalDao.Get.

func (*UniversalDaoMongo) GetAll

func (dao *UniversalDaoMongo) GetAll(filter godal.FilterOpt, sorting *godal.SortingOpt) ([]*UniversalBo, error)

GetAll implements UniversalDao.GetAll.

func (*UniversalDaoMongo) GetDefaultUboOpts added in v0.5.7

func (dao *UniversalDaoMongo) GetDefaultUboOpts() []UboOpt

GetDefaultUboOpts returns the default options to be used by the DAO when creating UniversalBo instances.

Available since v0.5.7

func (*UniversalDaoMongo) GetN

func (dao *UniversalDaoMongo) GetN(fromOffset, maxNumRows int, filter godal.FilterOpt, sorting *godal.SortingOpt) ([]*UniversalBo, error)

GetN implements UniversalDao.GetN.

func (*UniversalDaoMongo) Init added in v0.5.7

func (dao *UniversalDaoMongo) Init() error

Init should be called to initialize the DAO instance before use.

Available since v0.5.7

func (*UniversalDaoMongo) Save

func (dao *UniversalDaoMongo) Save(bo *UniversalBo) (bool, *UniversalBo, error)

Save implements UniversalDao.Save.

func (*UniversalDaoMongo) SetDefaultUboOpts added in v0.5.7

func (dao *UniversalDaoMongo) SetDefaultUboOpts(uboOpts []UboOpt) *UniversalDaoMongo

SetDefaultUboOpts sets the default options to be used by the DAO when creating UniversalBo instances.

Available since v0.5.7

func (*UniversalDaoMongo) ToGenericBo

func (dao *UniversalDaoMongo) ToGenericBo(ubo *UniversalBo) godal.IGenericBo

ToGenericBo implements UniversalDao.ToGenericBo.

func (*UniversalDaoMongo) ToUniversalBo

func (dao *UniversalDaoMongo) ToUniversalBo(gbo godal.IGenericBo) *UniversalBo

ToUniversalBo implements UniversalDao.ToUniversalBo.

func (*UniversalDaoMongo) Update

func (dao *UniversalDaoMongo) Update(bo *UniversalBo) (bool, error)

Update implements UniversalDao.Update.

type UniversalDaoSql

type UniversalDaoSql struct {
	sql.IGenericDaoSql
	// contains filtered or unexported fields
}

UniversalDaoSql is SQL-based implementation of UniversalDao.

func (*UniversalDaoSql) Create

func (dao *UniversalDaoSql) Create(bo *UniversalBo) (bool, error)

Create implements UniversalDao.Create.

func (*UniversalDaoSql) Delete

func (dao *UniversalDaoSql) Delete(bo *UniversalBo) (bool, error)

Delete implements UniversalDao.Delete.

func (*UniversalDaoSql) GdaoCreateFilter

func (dao *UniversalDaoSql) GdaoCreateFilter(tableName string, bo godal.IGenericBo) godal.FilterOpt

GdaoCreateFilter implements IGenericDao.GdaoCreateFilter.

func (*UniversalDaoSql) Get

func (dao *UniversalDaoSql) Get(id string) (*UniversalBo, error)

Get implements UniversalDao.Get.

func (*UniversalDaoSql) GetAll

func (dao *UniversalDaoSql) GetAll(filter godal.FilterOpt, sorting *godal.SortingOpt) ([]*UniversalBo, error)

GetAll implements UniversalDao.GetAll.

func (*UniversalDaoSql) GetDefaultSorting added in v0.5.7

func (dao *UniversalDaoSql) GetDefaultSorting() *godal.SortingOpt

GetDefaultSorting returns the default sorting option to be used for querying BOs.

See FuncFilterGeneratorSql for more information.

Available since v0.5.7

func (*UniversalDaoSql) GetDefaultUboOpts added in v0.5.7

func (dao *UniversalDaoSql) GetDefaultUboOpts() []UboOpt

GetDefaultUboOpts returns the default options to be used by the DAO when creating UniversalBo instances.

Available since v0.5.7

func (*UniversalDaoSql) GetFuncFilterGeneratorSql added in v0.5.7

func (dao *UniversalDaoSql) GetFuncFilterGeneratorSql() FuncFilterGeneratorSql

GetFuncFilterGeneratorSql returns the function used to generate filter for universal BO.

See FuncFilterGeneratorSql for more information.

Available since v0.5.7

func (*UniversalDaoSql) GetN

func (dao *UniversalDaoSql) GetN(fromOffset, maxNumRows int, filter godal.FilterOpt, sorting *godal.SortingOpt) ([]*UniversalBo, error)

GetN implements UniversalDao.GetN.

func (*UniversalDaoSql) Init added in v0.5.7

func (dao *UniversalDaoSql) Init() error

Init should be called to initialize the DAO instance before use.

Available since v0.5.7

func (*UniversalDaoSql) Save

func (dao *UniversalDaoSql) Save(bo *UniversalBo) (bool, *UniversalBo, error)

Save implements UniversalDao.Save.

func (*UniversalDaoSql) SetDefaultSorting added in v0.5.7

func (dao *UniversalDaoSql) SetDefaultSorting(defaultSorting *godal.SortingOpt) *UniversalDaoSql

SetDefaultSorting sets the default sorting option to be used for querying BOs.

See FuncFilterGeneratorSql for more information.

Available since v0.5.7

func (*UniversalDaoSql) SetDefaultUboOpts added in v0.5.7

func (dao *UniversalDaoSql) SetDefaultUboOpts(uboOpts []UboOpt) *UniversalDaoSql

SetDefaultUboOpts sets the default options to be used by the DAO when creating UniversalBo instances.

Available since v0.5.7

func (*UniversalDaoSql) SetFuncFilterGeneratorSql added in v0.5.7

func (dao *UniversalDaoSql) SetFuncFilterGeneratorSql(funcFilterGeneratorSql FuncFilterGeneratorSql) *UniversalDaoSql

SetFuncFilterGeneratorSql returns the function used to generate filter for universal BO.

See FuncFilterGeneratorSql for more information.

Available since v0.5.7

func (*UniversalDaoSql) ToGenericBo

func (dao *UniversalDaoSql) ToGenericBo(ubo *UniversalBo) godal.IGenericBo

ToGenericBo transforms business object to godal.IGenericBo.

func (*UniversalDaoSql) ToUniversalBo

func (dao *UniversalDaoSql) ToUniversalBo(gbo godal.IGenericBo) *UniversalBo

ToUniversalBo transforms godal.IGenericBo to business object.

func (*UniversalDaoSql) Update

func (dao *UniversalDaoSql) Update(bo *UniversalBo) (bool, error)

Update implements UniversalDao.Update.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL