gdb

package
v2.0.7-feature-clickho... Latest Latest
Warning

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

 Go to latest Published: Apr 25, 2022 License: MIT Imports: 48 Imported by: 234

Documentation

Overview

Package gdb provides ORM features for popular relationship databases.

Example (Transaction) 
db.Transaction(context.TODO(), func(ctx context.Context, tx *gdb.TX) error {
	// user
	result, err := tx.Insert("user", g.Map{
		"passport": "john",
		"password": "12345678",
		"nickname": "JohnGuo",
	})
	if err != nil {
		return err
	}
	// user_detail
	id, err := result.LastInsertId()
	if err != nil {
		return err
	}
	_, err = tx.Insert("user_detail", g.Map{
		"uid":       id,
		"site":      "https://johng.cn",
		"true_name": "GuoQiang",
	})
	if err != nil {
		return err
	}
	return nil
})

Output:

Index

Examples

Constants

View Source 
const (
	InsertOptionDefault = 0
	InsertOptionReplace = 1
	InsertOptionSave    = 2
	InsertOptionIgnore  = 3
)
View Source 
const (
	SqlTypeBegin               = "DB.Begin"
	SqlTypeTXCommit            = "TX.Commit"
	SqlTypeTXRollback          = "TX.Rollback"
	SqlTypeExecContext         = "DB.ExecContext"
	SqlTypeQueryContext        = "DB.QueryContext"
	SqlTypePrepareContext      = "DB.PrepareContext"
	SqlTypeStmtExecContext     = "DB.Statement.ExecContext"
	SqlTypeStmtQueryContext    = "DB.Statement.QueryContext"
	SqlTypeStmtQueryRowContext = "DB.Statement.QueryRowContext"
)
View Source 
const (
	OrmTagForStruct    = "orm"
	OrmTagForTable     = "table"
	OrmTagForWith      = "with"
	OrmTagForWithWhere = "where"
	OrmTagForWithOrder = "order"
	OrmTagForDo        = "do"
)
View Source 
const (
	DefaultGroupName = "default" // Default group name.
)
View Source 
const (
	DriverNameMysql = `mysql`
)

Variables

This section is empty.

Functions

func AddConfigNode 

func AddConfigNode(group string, node ConfigNode)

AddConfigNode adds one node configuration to configuration of given group.

func AddDefaultConfigGroup 

func AddDefaultConfigGroup(nodes ConfigGroup)

AddDefaultConfigGroup adds multiple node configurations to configuration of default group.

func AddDefaultConfigNode 

func AddDefaultConfigNode(node ConfigNode)

AddDefaultConfigNode adds one node configuration to configuration of default group.

func DataToMapDeep 

func DataToMapDeep(value interface{}) map[string]interface{}

DataToMapDeep converts `value` to map type recursively(if attribute struct is embedded). The parameter `value` should be type of *map/map/*struct/struct. It supports embedded struct definition for struct.

func FormatSqlWithArgs 

func FormatSqlWithArgs(sql string, args []interface{}) string

FormatSqlWithArgs binds the arguments to the sql string and returns a complete sql string, just for debugging.

func GetDefaultGroup 

func GetDefaultGroup() string

GetDefaultGroup returns the { name of default configuration.

func GetInsertOperationByOption 

func GetInsertOperationByOption(option int) string

GetInsertOperationByOption returns proper insert option with given parameter `option`.

func GetPrimaryKeyCondition 

func GetPrimaryKeyCondition(primary string, where ...interface{}) (newWhereCondition []interface{})

GetPrimaryKeyCondition returns a new where condition by primary field name. The optional parameter `where` is like follows: 123 => primary=123 []int{1, 2, 3} => primary IN(1,2,3) "john" => primary='john' []string{"john", "smith"} => primary IN('john','smith') g.Map{"id": g.Slice{1,2,3}} => id IN(1,2,3) g.Map{"id": 1, "name": "john"} => id=1 AND name='john' etc.

Note that it returns the given `where` parameter directly if the `primary` is empty or length of `where` > 1.

func IsConfigured 

func IsConfigured() bool

IsConfigured checks and returns whether the database configured. It returns true if any configuration exists.

func ListItemValues 

func ListItemValues(list interface{}, key interface{}, subKey ...interface{}) (values []interface{})

ListItemValues retrieves and returns the elements of all item struct/map with key `key`. Note that the parameter `list` should be type of slice which contains elements of map or struct, or else it returns an empty slice.

The parameter `list` supports types like: []map[string]interface{} []map[string]sub-map []struct []struct:sub-struct Note that the sub-map/sub-struct makes sense only if the optional parameter `subKey` is given. See gutil.ListItemValues.

func ListItemValuesUnique 

func ListItemValuesUnique(list interface{}, key string, subKey ...interface{}) []interface{}

ListItemValuesUnique retrieves and returns the unique elements of all struct/map with key `key`. Note that the parameter `list` should be type of slice which contains elements of map or struct, or else it returns an empty slice. See gutil.ListItemValuesUnique.

func Register 

func Register(name string, driver Driver) error

Register registers custom database driver to gdb.

func SetConfig 

func SetConfig(config Config)

SetConfig sets the global configuration for package. It will overwrite the old configuration of package.

func SetConfigGroup 

func SetConfigGroup(group string, nodes ConfigGroup)

SetConfigGroup sets the configuration for given group.

func SetDefaultGroup 

func SetDefaultGroup(name string)

SetDefaultGroup sets the group name for default configuration.

func WithDB added in v2.0.5 

func WithDB(ctx context.Context, db DB) context.Context

WithDB injects given db object into context and returns a new context.

func WithTX 

func WithTX(ctx context.Context, tx *TX) context.Context

WithTX injects given transaction object into context and returns a new context.

Types

type CacheOption 

type CacheOption struct {
	// Duration is the TTL for the cache.
	// If the parameter `Duration` < 0, which means it clear the cache with given `Name`.
	// If the parameter `Duration` = 0, which means it never expires.
	// If the parameter `Duration` > 0, which means it expires after `Duration`.
	Duration time.Duration

	// Name is an optional unique name for the cache.
	// The Name is used to bind a name to the cache, which means you can later control the cache
	// like changing the `duration` or clearing the cache with specified Name.
	Name string

	// Force caches the query result whatever the result is nil or not.
	// It is used to avoid Cache Penetration.
	Force bool
}

type ChunkHandler 

type ChunkHandler func(result Result, err error) bool

ChunkHandler is a function that is used in function Chunk, which handles given Result and error. It returns true if it wants to continue chunking, or else it returns false to stop chunking.

type Config 

type Config map[string]ConfigGroup

Config is the configuration management object.

type ConfigGroup 

type ConfigGroup []ConfigNode

ConfigGroup is a slice of configuration node for specified named group.

func GetConfig 

func GetConfig(group string) ConfigGroup

GetConfig retrieves and returns the configuration of given group.

type ConfigNode 

type ConfigNode struct {
	Host                 string        `json:"host"`                 // Host of server, ip or domain like: 127.0.0.1, localhost
	Port                 string        `json:"port"`                 // Port, it's commonly 3306.
	User                 string        `json:"user"`                 // Authentication username.
	Pass                 string        `json:"pass"`                 // Authentication password.
	Name                 string        `json:"name"`                 // Default used database name.
	Type                 string        `json:"type"`                 // Database type: mysql, sqlite, mssql, pgsql, oracle.
	Link                 string        `json:"link"`                 // (Optional) Custom link information, when it is used, configuration Host/Port/User/Pass/Name are ignored.
	Role                 string        `json:"role"`                 // (Optional, "master" in default) Node role, used for master-slave mode: master, slave.
	Debug                bool          `json:"debug"`                // (Optional) Debug mode enables debug information logging and output.
	Prefix               string        `json:"prefix"`               // (Optional) Table prefix.
	DryRun               bool          `json:"dryRun"`               // (Optional) Dry run, which does SELECT but no INSERT/UPDATE/DELETE statements.
	Weight               int           `json:"weight"`               // (Optional) Weight for load balance calculating, it's useless if there's just one node.
	Charset              string        `json:"charset"`              // (Optional, "utf8mb4" in default) Custom charset when operating on database.
	Timezone             string        `json:"timezone"`             // (Optional) Sets the time zone for displaying and interpreting time stamps.
	MaxIdleConnCount     int           `json:"maxIdle"`              // (Optional) Max idle connection configuration for underlying connection pool.
	MaxOpenConnCount     int           `json:"maxOpen"`              // (Optional) Max open connection configuration for underlying connection pool.
	MaxConnLifeTime      time.Duration `json:"maxLifeTime"`          // (Optional) Max amount of time a connection may be idle before being closed.
	QueryTimeout         time.Duration `json:"queryTimeout"`         // (Optional) Max query time for per dql.
	ExecTimeout          time.Duration `json:"execTimeout"`          // (Optional) Max exec time for dml.
	TranTimeout          time.Duration `json:"tranTimeout"`          // (Optional) Max exec time time for a transaction.
	PrepareTimeout       time.Duration `json:"prepareTimeout"`       // (Optional) Max exec time time for prepare operation.
	CreatedAt            string        `json:"createdAt"`            // (Optional) The filed name of table for automatic-filled created datetime.
	UpdatedAt            string        `json:"updatedAt"`            // (Optional) The filed name of table for automatic-filled updated datetime.
	DeletedAt            string        `json:"deletedAt"`            // (Optional) The filed name of table for automatic-filled updated datetime.
	TimeMaintainDisabled bool          `json:"timeMaintainDisabled"` // (Optional) Disable the automatic time maintaining feature.
}

ConfigNode is configuration for one node.

func (*ConfigNode) String 

func (node *ConfigNode) String() string

String returns the node as string.

type Core 

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

Core is the base struct for database management.

func (*Core) Begin 

func (c *Core) Begin(ctx context.Context) (tx *TX, err error)

Begin starts and returns the transaction object. You should call Commit or Rollback functions of the transaction object if you no longer use the transaction. Commit or Rollback functions will also close the transaction automatically.

func (*Core) Close 

func (c *Core) Close(ctx context.Context) (err error)

Close closes the database and prevents new queries from starting. Close then waits for all queries that have started processing on the server to finish.

It is rare to Close a DB, as the DB handle is meant to be long-lived and shared between many goroutines.

func (*Core) ConvertDataForRecord 

func (c *Core) ConvertDataForRecord(ctx context.Context, value interface{}) map[string]interface{}

ConvertDataForRecord is a very important function, which does converting for any data that will be inserted into table/collection as a record.

The parameter `value` should be type of *map/map/*struct/struct. It supports embedded struct definition for struct.

func (*Core) ConvertDataForRecordValue 

func (c *Core) ConvertDataForRecordValue(ctx context.Context, value interface{}) interface{}

func (*Core) Ctx 

func (c *Core) Ctx(ctx context.Context) DB

Ctx is a chaining function, which creates and returns a new DB that is a shallow copy of current DB object and with given context in it. Note that this returned DB object can be used only once, so do not assign it to a global or package variable for long using.

func (*Core) Delete 

func (c *Core) Delete(ctx context.Context, table string, condition interface{}, args ...interface{}) (result sql.Result, err error)

Delete does "DELETE FROM ... " statement for the table.

The parameter `condition` can be type of string/map/gmap/slice/struct/*struct, etc. It is commonly used with parameter `args`. Eg: "uid=10000", "uid", 10000 "money>? AND name like ?", 99999, "vip_%" "status IN (?)", g.Slice{1,2,3} "age IN(?,?)", 18, 50 User{ Id : 1, UserName : "john"}.

func (*Core) DoCommit 

func (c *Core) DoCommit(ctx context.Context, in DoCommitInput) (out DoCommitOutput, err error)

DoCommit commits current sql and arguments to underlying sql driver.

func (*Core) DoDelete 

func (c *Core) DoDelete(ctx context.Context, link Link, table string, condition string, args ...interface{}) (result sql.Result, err error)

DoDelete does "DELETE FROM ... " statement for the table. This function is usually used for custom interface definition, you do not need call it manually.

func (*Core) DoExec 

func (c *Core) DoExec(ctx context.Context, link Link, sql string, args ...interface{}) (result sql.Result, err error)

DoExec commits the sql string and its arguments to underlying driver through given link object and returns the execution result.

func (*Core) DoFilter 

func (c *Core) DoFilter(ctx context.Context, link Link, sql string, args []interface{}) (newSql string, newArgs []interface{}, err error)

DoFilter is a hook function, which filters the sql and its arguments before it's committed to underlying driver. The parameter `link` specifies the current database connection operation object. You can modify the sql string `sql` and its arguments `args` as you wish before they're committed to driver.

func (*Core) DoInsert 

func (c *Core) DoInsert(ctx context.Context, link Link, table string, list List, option DoInsertOption) (result sql.Result, err error)

DoInsert inserts or updates data forF given table. This function is usually used for custom interface definition, you do not need call it manually. The parameter `data` can be type of map/gmap/struct/*struct/[]map/[]struct, etc. Eg: Data(g.Map{"uid": 10000, "name":"john"}) Data(g.Slice{g.Map{"uid": 10000, "name":"john"}, g.Map{"uid": 20000, "name":"smith"})

The parameter `option` values are as follows: 0: insert: just insert, if there's unique/primary key in the data, it returns error; 1: replace: if there's unique/primary key in the data, it deletes it from table and inserts a new one; 2: save: if there's unique/primary key in the data, it updates it or else inserts a new one; 3: ignore: if there's unique/primary key in the data, it ignores the inserting;

func (*Core) DoPrepare 

func (c *Core) DoPrepare(ctx context.Context, link Link, sql string) (stmt *Stmt, err error)

DoPrepare calls prepare function on given link object and returns the statement object.

func (*Core) DoQuery 

func (c *Core) DoQuery(ctx context.Context, link Link, sql string, args ...interface{}) (result Result, err error)

DoQuery commits the sql string and its arguments to underlying driver through given link object and returns the execution result.

func (*Core) DoSelect added in v2.0.5 

func (c *Core) DoSelect(ctx context.Context, link Link, sql string, args ...interface{}) (result Result, err error)

DoSelect queries and returns data records from database.

func (*Core) DoUpdate 

func (c *Core) DoUpdate(ctx context.Context, link Link, table string, data interface{}, condition string, args ...interface{}) (result sql.Result, err error)

DoUpdate does "UPDATE ... " statement for the table. This function is usually used for custom interface definition, you do not need to call it manually.

func (*Core) Exec 

func (c *Core) Exec(ctx context.Context, sql string, args ...interface{}) (result sql.Result, err error)

Exec commits one query SQL to underlying driver and returns the execution result. It is most commonly used for data inserting and updating.

func (*Core) GetAll 

func (c *Core) GetAll(ctx context.Context, sql string, args ...interface{}) (Result, error)

GetAll queries and returns data records from database.

func (*Core) GetArray 

func (c *Core) GetArray(ctx context.Context, sql string, args ...interface{}) ([]Value, error)

GetArray queries and returns data values as slice from database. Note that if there are multiple columns in the result, it returns just one column values randomly.

func (*Core) GetCache 

func (c *Core) GetCache() *gcache.Cache

GetCache returns the internal cache object.

func (*Core) GetChars 

func (c *Core) GetChars() (charLeft string, charRight string)

GetChars returns the security char for current database. It does nothing in default.

func (*Core) GetConfig 

func (c *Core) GetConfig() *ConfigNode

GetConfig returns the current used node configuration.

func (*Core) GetCore 

func (c *Core) GetCore() *Core

GetCore returns the underlying *Core object.

func (*Core) GetCount 

func (c *Core) GetCount(ctx context.Context, sql string, args ...interface{}) (int, error)

GetCount queries and returns the count from database.

func (*Core) GetCtx 

func (c *Core) GetCtx() context.Context

GetCtx returns the context for current DB. It returns `context.Background()` is there's no context previously set.

func (*Core) GetCtxTimeout 

func (c *Core) GetCtxTimeout(ctx context.Context, timeoutType int) (context.Context, context.CancelFunc)

GetCtxTimeout returns the context and cancel function for specified timeout type.

func (*Core) GetDebug 

func (c *Core) GetDebug() bool

GetDebug returns the debug value.

func (*Core) GetDryRun 

func (c *Core) GetDryRun() bool

GetDryRun returns the DryRun value.

func (*Core) GetGroup 

func (c *Core) GetGroup() string

GetGroup returns the group string configured.

func (*Core) GetIgnoreResultFromCtx added in v2.1.0 

func (c *Core) GetIgnoreResultFromCtx(ctx context.Context) bool

func (*Core) GetInternalCtxDataFromCtx added in v2.1.0 

func (c *Core) GetInternalCtxDataFromCtx(ctx context.Context) *internalCtxData
func (c *Core) GetLink(ctx context.Context, master bool, schema string) (Link, error)

GetLink creates and returns the underlying database link object with transaction checks. The parameter `master` specifies whether using the master node if master-slave configured.

func (*Core) GetLogger 

func (c *Core) GetLogger() *glog.Logger

GetLogger returns the (logger) of the orm.

func (*Core) GetNeedParsedSqlFromCtx 

func (c *Core) GetNeedParsedSqlFromCtx(ctx context.Context) bool

func (*Core) GetOne 

func (c *Core) GetOne(ctx context.Context, sql string, args ...interface{}) (Record, error)

GetOne queries and returns one record from database.

func (*Core) GetPrefix 

func (c *Core) GetPrefix() string

GetPrefix returns the table prefix string configured.

func (*Core) GetScan 

func (c *Core) GetScan(ctx context.Context, pointer interface{}, sql string, args ...interface{}) error

GetScan queries one or more records from database and converts them to given struct or struct array.

If parameter `pointer` is type of struct pointer, it calls GetStruct internally for the conversion. If parameter `pointer` is type of slice, it calls GetStructs internally for conversion.

func (*Core) GetSchema 

func (c *Core) GetSchema() string

GetSchema returns the schema configured.

func (*Core) GetStruct 

func (c *Core) GetStruct(ctx context.Context, pointer interface{}, sql string, args ...interface{}) error

GetStruct queries one record from database and converts it to given struct. The parameter `pointer` should be a pointer to struct.

func (*Core) GetStructs 

func (c *Core) GetStructs(ctx context.Context, pointer interface{}, sql string, args ...interface{}) error

GetStructs queries records from database and converts them to given struct. The parameter `pointer` should be type of struct slice: []struct/[]*struct.

func (*Core) GetValue 

func (c *Core) GetValue(ctx context.Context, sql string, args ...interface{}) (Value, error)

GetValue queries and returns the field value from database. The sql should query only one field from database, or else it returns only one field of the result.

func (*Core) HasField 

func (c *Core) HasField(table, field string, schema ...string) (bool, error)

HasField determine whether the field exists in the table.

func (*Core) HasTable 

func (c *Core) HasTable(name string) (bool, error)

HasTable determine whether the table name exists in the database.

func (*Core) InjectIgnoreResult added in v2.1.0 

func (c *Core) InjectIgnoreResult(ctx context.Context) context.Context

func (*Core) InjectInternalCtxData added in v2.1.0 

func (c *Core) InjectInternalCtxData(ctx context.Context) context.Context

func (*Core) InjectNeedParsedSql 

func (c *Core) InjectNeedParsedSql(ctx context.Context) context.Context

func (*Core) Insert 

func (c *Core) Insert(ctx context.Context, table string, data interface{}, batch ...int) (sql.Result, error)

Insert does "INSERT INTO ..." statement for the table. If there's already one unique record of the data in the table, it returns error.

The parameter `data` can be type of map/gmap/struct/*struct/[]map/[]struct, etc. Eg: Data(g.Map{"uid": 10000, "name":"john"}) Data(g.Slice{g.Map{"uid": 10000, "name":"john"}, g.Map{"uid": 20000, "name":"smith"})

The parameter `batch` specifies the batch operation count when given data is slice.

func (*Core) InsertAndGetId 

func (c *Core) InsertAndGetId(ctx context.Context, table string, data interface{}, batch ...int) (int64, error)

InsertAndGetId performs action Insert and returns the last insert id that automatically generated.

func (*Core) InsertIgnore 

func (c *Core) InsertIgnore(ctx context.Context, table string, data interface{}, batch ...int) (sql.Result, error)

InsertIgnore does "INSERT IGNORE INTO ..." statement for the table. If there's already one unique record of the data in the table, it ignores the inserting.

The parameter `data` can be type of map/gmap/struct/*struct/[]map/[]struct, etc. Eg: Data(g.Map{"uid": 10000, "name":"john"}) Data(g.Slice{g.Map{"uid": 10000, "name":"john"}, g.Map{"uid": 20000, "name":"smith"})

The parameter `batch` specifies the batch operation count when given data is slice.

func (Core) MarshalJSON 

func (c Core) MarshalJSON() ([]byte, error)

MarshalJSON implements the interface MarshalJSON for json.Marshal. It just returns the pointer address.

Note that this interface implements mainly for workaround for a json infinite loop bug of Golang version < v1.14.

func (*Core) Master 

func (c *Core) Master(schema ...string) (*sql.DB, error)

Master creates and returns a connection from master node if master-slave configured. It returns the default connection if master-slave not configured. 

func (c *Core) MasterLink(schema ...string) (Link, error)

MasterLink acts like function Master but with additional `schema` parameter specifying the schema for the connection. It is defined for internal usage. Also see Master.

func (*Core) Model 

func (c *Core) Model(tableNameQueryOrStruct ...interface{}) *Model

Model creates and returns a new ORM model from given schema. The parameter `tableNameQueryOrStruct` can be more than one table names, and also alias name, like:

  1. Model names: db.Model("user") db.Model("user u") db.Model("user, user_detail") db.Model("user u, user_detail ud")
  2. Model name with alias: db.Model("user", "u")
  3. Model name with sub-query: db.Model("? AS a, ? AS b", subQuery1, subQuery2)

func (*Core) PingMaster 

func (c *Core) PingMaster() error

PingMaster pings the master node to check authentication or keeps the connection alive.

func (*Core) PingSlave 

func (c *Core) PingSlave() error

PingSlave pings the slave node to check authentication or keeps the connection alive.

func (*Core) Prepare 

func (c *Core) Prepare(ctx context.Context, sql string, execOnMaster ...bool) (*Stmt, error)

Prepare creates a prepared statement for later queries or executions. Multiple queries or executions may be run concurrently from the returned statement. The caller must call the statement's Close method when the statement is no longer needed.

The parameter `execOnMaster` specifies whether executing the sql on master node, or else it executes the sql on slave node if master-slave configured.

func (*Core) Query 

func (c *Core) Query(ctx context.Context, sql string, args ...interface{}) (result Result, err error)

Query commits one query SQL to underlying driver and returns the execution result. It is most commonly used for data querying.

func (*Core) QuotePrefixTableName 

func (c *Core) QuotePrefixTableName(table string) string

QuotePrefixTableName adds prefix string and quotes chars for the table. It handles table string like: "user", "user u", "user,user_detail", "user u, user_detail ut", "user as u, user_detail as ut".

Note that, this will automatically checks the table prefix whether already added, if true it does nothing to the table name, or else adds the prefix to the table name.

func (*Core) QuoteString 

func (c *Core) QuoteString(s string) string

QuoteString quotes string with quote chars. Strings like: "user", "user u", "user,user_detail", "user u, user_detail ut", "u.id asc".

The meaning of a `string` can be considered as part of a statement string including columns.

func (*Core) QuoteWord 

func (c *Core) QuoteWord(s string) string

QuoteWord checks given string `s` a word, if true it quotes `s` with security chars of the database and returns the quoted string; or else it returns `s` without any change.

The meaning of a `word` can be considered as a column name.

func (*Core) Raw 

func (c *Core) Raw(rawSql string, args ...interface{}) *Model

Raw creates and returns a model based on a raw sql not a table. Example: 

db.Raw("SELECT * FROM `user` WHERE `name` = ?", "john").Scan(&result)

func (*Core) Replace 

func (c *Core) Replace(ctx context.Context, table string, data interface{}, batch ...int) (sql.Result, error)

Replace does "REPLACE INTO ..." statement for the table. If there's already one unique record of the data in the table, it deletes the record and inserts a new one.

The parameter `data` can be type of map/gmap/struct/*struct/[]map/[]struct, etc. Eg: Data(g.Map{"uid": 10000, "name":"john"}) Data(g.Slice{g.Map{"uid": 10000, "name":"john"}, g.Map{"uid": 20000, "name":"smith"})

The parameter `data` can be type of map/gmap/struct/*struct/[]map/[]struct, etc. If given data is type of slice, it then does batch replacing, and the optional parameter `batch` specifies the batch operation count.

func (*Core) RowsToResult 

func (c *Core) RowsToResult(ctx context.Context, rows *sql.Rows) (Result, error)

RowsToResult converts underlying data record type sql.Rows to Result type.

func (*Core) Save 

func (c *Core) Save(ctx context.Context, table string, data interface{}, batch ...int) (sql.Result, error)

Save does "INSERT INTO ... ON DUPLICATE KEY UPDATE..." statement for the table. It updates the record if there's primary or unique index in the saving data, or else it inserts a new record into the table.

The parameter `data` can be type of map/gmap/struct/*struct/[]map/[]struct, etc. Eg: Data(g.Map{"uid": 10000, "name":"john"}) Data(g.Slice{g.Map{"uid": 10000, "name":"john"}, g.Map{"uid": 20000, "name":"smith"})

If given data is type of slice, it then does batch saving, and the optional parameter `batch` specifies the batch operation count.

func (*Core) Schema 

func (c *Core) Schema(schema string) *Schema

Schema creates and returns a schema.

func (*Core) SetDebug 

func (c *Core) SetDebug(debug bool)

SetDebug enables/disables the debug mode.

func (*Core) SetDryRun 

func (c *Core) SetDryRun(enabled bool)

SetDryRun enables/disables the DryRun feature.

func (*Core) SetLogger 

func (c *Core) SetLogger(logger *glog.Logger)

SetLogger sets the logger for orm.

func (*Core) SetMaxConnLifeTime 

func (c *Core) SetMaxConnLifeTime(d time.Duration)

SetMaxConnLifeTime sets the maximum amount of time a connection may be reused.

Expired connections may be closed lazily before reuse.

If d <= 0, connections are not closed due to a connection's age.

func (*Core) SetMaxIdleConnCount 

func (c *Core) SetMaxIdleConnCount(n int)

SetMaxIdleConnCount sets the maximum number of connections in the idle connection pool.

If MaxOpenConns is greater than 0 but less than the new MaxIdleConns, then the new MaxIdleConns will be reduced to match the MaxOpenConns limit.

If n <= 0, no idle connections are retained.

The default max idle connections is currently 2. This may change in a future release.

func (*Core) SetMaxOpenConnCount 

func (c *Core) SetMaxOpenConnCount(n int)

SetMaxOpenConnCount sets the maximum number of open connections to the database.

If MaxIdleConns is greater than 0 and the new MaxOpenConns is less than MaxIdleConns, then MaxIdleConns will be reduced to match the new MaxOpenConns limit.

If n <= 0, then there is no limit on the number of open connections. The default is 0 (unlimited).

func (*Core) Slave 

func (c *Core) Slave(schema ...string) (*sql.DB, error)

Slave creates and returns a connection from slave node if master-slave configured. It returns the default connection if master-slave not configured. 

func (c *Core) SlaveLink(schema ...string) (Link, error)

SlaveLink acts like function Slave but with additional `schema` parameter specifying the schema for the connection. It is defined for internal usage. Also see Slave.

func (*Core) TableFields 

func (c *Core) TableFields(table string, schema ...string) (fields map[string]*TableField, err error)

TableFields retrieves and returns the fields' information of specified table of current schema.

Note that it returns a map containing the field name and its corresponding fields. As a map is unsorted, the TableField struct has an "Index" field marks its sequence in the fields.

It's using cache feature to enhance the performance, which is never expired util the process restarts.

It does nothing in default.

func (*Core) Tables 

func (c *Core) Tables(schema ...string) (tables []string, err error)

Tables retrieves and returns the tables of current schema. It's mainly used in cli tool chain for automatically generating the models.

It does nothing in default.

func (*Core) Transaction 

func (c *Core) Transaction(ctx context.Context, f func(ctx context.Context, tx *TX) error) (err error)

Transaction wraps the transaction logic using function `f`. It rollbacks the transaction and returns the error from function `f` if it returns non-nil error. It commits the transaction and returns nil if function `f` returns nil.

Note that, you should not Commit or Rollback the transaction in function `f` as it is automatically handled by this function.

func (*Core) Union 

func (c *Core) Union(unions ...*Model) *Model

Union does "(SELECT xxx FROM xxx) UNION (SELECT xxx FROM xxx) ..." statement.

func (*Core) UnionAll 

func (c *Core) UnionAll(unions ...*Model) *Model

UnionAll does "(SELECT xxx FROM xxx) UNION ALL (SELECT xxx FROM xxx) ..." statement.

func (*Core) Update 

func (c *Core) Update(ctx context.Context, table string, data interface{}, condition interface{}, args ...interface{}) (sql.Result, error)

Update does "UPDATE ... " statement for the table.

The parameter `data` can be type of string/map/gmap/struct/*struct, etc. Eg: "uid=10000", "uid", 10000, g.Map{"uid": 10000, "name":"john"}

The parameter `condition` can be type of string/map/gmap/slice/struct/*struct, etc. It is commonly used with parameter `args`. Eg: "uid=10000", "uid", 10000 "money>? AND name like ?", 99999, "vip_%" "status IN (?)", g.Slice{1,2,3} "age IN(?,?)", 18, 50 User{ Id : 1, UserName : "john"}.

func (*Core) With 

func (c *Core) With(objects ...interface{}) *Model

With creates and returns an ORM model based on metadata of given object.

type Counter 

type Counter struct {
	Field string
	Value float64
}

Counter is the type for update count.

type DB 

type DB interface {

	// Model creates and returns a new ORM model from given schema.
	// The parameter `table` can be more than one table names, and also alias name, like:
	// 1. Model names:
	//    Model("user")
	//    Model("user u")
	//    Model("user, user_detail")
	//    Model("user u, user_detail ud")
	// 2. Model name with alias: Model("user", "u")
	// Also see Core.Model.
	Model(tableNameOrStruct ...interface{}) *Model

	// Raw creates and returns a model based on a raw sql not a table.
	Raw(rawSql string, args ...interface{}) *Model

	// Schema creates and returns a schema.
	// Also see Core.Schema.
	Schema(schema string) *Schema

	// With creates and returns an ORM model based on metadata of given object.
	// Also see Core.With.
	With(objects ...interface{}) *Model

	// Open creates a raw connection object for database with given node configuration.
	// Note that it is not recommended using the function manually.
	// Also see DriverMysql.Open.
	Open(config *ConfigNode) (*sql.DB, error)

	// Ctx is a chaining function, which creates and returns a new DB that is a shallow copy
	// of current DB object and with given context in it.
	// Also see Core.Ctx.
	Ctx(ctx context.Context) DB

	// Close closes the database and prevents new queries from starting.
	// Close then waits for all queries that have started processing on the server
	// to finish.
	//
	// It is rare to Close a DB, as the DB handle is meant to be
	// long-lived and shared between many goroutines.
	Close(ctx context.Context) error

	Query(ctx context.Context, sql string, args ...interface{}) (Result, error)    // See Core.Query.
	Exec(ctx context.Context, sql string, args ...interface{}) (sql.Result, error) // See Core.Exec.
	Prepare(ctx context.Context, sql string, execOnMaster ...bool) (*Stmt, error)  // See Core.Prepare.

	Insert(ctx context.Context, table string, data interface{}, batch ...int) (sql.Result, error)                               // See Core.Insert.
	InsertIgnore(ctx context.Context, table string, data interface{}, batch ...int) (sql.Result, error)                         // See Core.InsertIgnore.
	InsertAndGetId(ctx context.Context, table string, data interface{}, batch ...int) (int64, error)                            // See Core.InsertAndGetId.
	Replace(ctx context.Context, table string, data interface{}, batch ...int) (sql.Result, error)                              // See Core.Replace.
	Save(ctx context.Context, table string, data interface{}, batch ...int) (sql.Result, error)                                 // See Core.Save.
	Update(ctx context.Context, table string, data interface{}, condition interface{}, args ...interface{}) (sql.Result, error) // See Core.Update.
	Delete(ctx context.Context, table string, condition interface{}, args ...interface{}) (sql.Result, error)                   // See Core.Delete.

	DoSelect(ctx context.Context, link Link, sql string, args ...interface{}) (result Result, err error)                                           // See Core.DoSelect.
	DoInsert(ctx context.Context, link Link, table string, data List, option DoInsertOption) (result sql.Result, err error)                        // See Core.DoInsert.
	DoUpdate(ctx context.Context, link Link, table string, data interface{}, condition string, args ...interface{}) (result sql.Result, err error) // See Core.DoUpdate.
	DoDelete(ctx context.Context, link Link, table string, condition string, args ...interface{}) (result sql.Result, err error)                   // See Core.DoDelete.

	DoQuery(ctx context.Context, link Link, sql string, args ...interface{}) (result Result, err error)    // See Core.DoQuery.
	DoExec(ctx context.Context, link Link, sql string, args ...interface{}) (result sql.Result, err error) // See Core.DoExec.

	DoFilter(ctx context.Context, link Link, sql string, args []interface{}) (newSql string, newArgs []interface{}, err error) // See Core.DoFilter.
	DoCommit(ctx context.Context, in DoCommitInput) (out DoCommitOutput, err error)                                            // See Core.DoCommit.

	DoPrepare(ctx context.Context, link Link, sql string) (*Stmt, error) // See Core.DoPrepare.

	GetAll(ctx context.Context, sql string, args ...interface{}) (Result, error)                // See Core.GetAll.
	GetOne(ctx context.Context, sql string, args ...interface{}) (Record, error)                // See Core.GetOne.
	GetValue(ctx context.Context, sql string, args ...interface{}) (Value, error)               // See Core.GetValue.
	GetArray(ctx context.Context, sql string, args ...interface{}) ([]Value, error)             // See Core.GetArray.
	GetCount(ctx context.Context, sql string, args ...interface{}) (int, error)                 // See Core.GetCount.
	GetScan(ctx context.Context, objPointer interface{}, sql string, args ...interface{}) error // See Core.GetScan.
	Union(unions ...*Model) *Model                                                              // See Core.Union.
	UnionAll(unions ...*Model) *Model                                                           // See Core.UnionAll.

	Master(schema ...string) (*sql.DB, error) // See Core.Master.
	Slave(schema ...string) (*sql.DB, error)  // See Core.Slave.

	PingMaster() error // See Core.PingMaster.
	PingSlave() error  // See Core.PingSlave.

	Begin(ctx context.Context) (*TX, error)                                           // See Core.Begin.
	Transaction(ctx context.Context, f func(ctx context.Context, tx *TX) error) error // See Core.Transaction.

	GetCache() *gcache.Cache            // See Core.GetCache.
	SetDebug(debug bool)                // See Core.SetDebug.
	GetDebug() bool                     // See Core.GetDebug.
	GetSchema() string                  // See Core.GetSchema.
	GetPrefix() string                  // See Core.GetPrefix.
	GetGroup() string                   // See Core.GetGroup.
	SetDryRun(enabled bool)             // See Core.SetDryRun.
	GetDryRun() bool                    // See Core.GetDryRun.
	SetLogger(logger *glog.Logger)      // See Core.SetLogger.
	GetLogger() *glog.Logger            // See Core.GetLogger.
	GetConfig() *ConfigNode             // See Core.GetConfig.
	SetMaxIdleConnCount(n int)          // See Core.SetMaxIdleConnCount.
	SetMaxOpenConnCount(n int)          // See Core.SetMaxOpenConnCount.
	SetMaxConnLifeTime(d time.Duration) // See Core.SetMaxConnLifeTime.

	GetCtx() context.Context                                                                         // See Core.GetCtx.
	GetCore() *Core                                                                                  // See Core.GetCore
	GetChars() (charLeft string, charRight string)                                                   // See Core.GetChars.
	Tables(ctx context.Context, schema ...string) (tables []string, err error)                       // See Core.Tables.
	TableFields(ctx context.Context, table string, schema ...string) (map[string]*TableField, error) // See Core.TableFields.
	ConvertDataForRecord(ctx context.Context, data interface{}) map[string]interface{}               // See Core.ConvertDataForRecord
	FilteredLink() string                                                                            // FilteredLink is used for filtering sensitive information in `Link` configuration before output it to tracing server.
}

DB defines the interfaces for ORM operations.

func DBFromCtx added in v2.0.5 

func DBFromCtx(ctx context.Context) DB

DBFromCtx retrieves and returns DB object from context.

func Instance 

func Instance(name ...string) (db DB, err error)

Instance returns an instance for DB operations. The parameter `name` specifies the configuration group name, which is DefaultGroupName in default.

func New 

func New(node ConfigNode) (db DB, err error)

New creates and returns an ORM object with given configuration node.

func NewByGroup 

func NewByGroup(group ...string) (db DB, err error)

NewByGroup creates and returns an ORM object with global configurations. The parameter `name` specifies the configuration group name, which is DefaultGroupName in default.

type DoCommitInput 

type DoCommitInput struct {
	Db            *sql.DB
	Tx            *sql.Tx
	Stmt          *sql.Stmt
	Link          Link
	Sql           string
	Args          []interface{}
	Type          string
	IsTransaction bool
}

DoCommitInput is the input parameters for function DoCommit.

type DoCommitOutput 

type DoCommitOutput struct {
	Result    sql.Result  // Result is the result of exec statement.
	Records   []Record    // Records is the result of query statement.
	Stmt      *Stmt       // Stmt is the Statement object result for Prepare.
	Tx        *TX         // Tx is the transaction object result for Begin.
	RawResult interface{} // RawResult is the underlying result, which might be sql.Result/*sql.Rows/*sql.Row.
}

DoCommitOutput is the output parameters for function DoCommit.

type DoInsertOption 

type DoInsertOption struct {
	OnDuplicateStr string                 // Custom string for `on duplicated` statement.
	OnDuplicateMap map[string]interface{} // Custom key-value map from `OnDuplicateEx` function for `on duplicated` statement.
	InsertOption   int                    // Insert operation in constant value.
	BatchCount     int                    // Batch count for batch inserting.
}

DoInsertOption is the input struct for function DoInsert.

type Driver 

type Driver interface {
	// New creates and returns a database object for specified database server.
	New(core *Core, node *ConfigNode) (DB, error)
}

Driver is the interface for integrating sql drivers into package gdb.

type DriverMysql 

type DriverMysql struct {
	*Core
}

DriverMysql is the driver for mysql database.

func (*DriverMysql) DoFilter 

func (d *DriverMysql) DoFilter(ctx context.Context, link Link, sql string, args []interface{}) (newSql string, newArgs []interface{}, err error)

DoFilter handles the sql before posts it to database. 

func (d *DriverMysql) FilteredLink() string

FilteredLink retrieves and returns filtered `linkInfo` that can be using for logging or tracing purpose.

func (*DriverMysql) GetChars 

func (d *DriverMysql) GetChars() (charLeft string, charRight string)

GetChars returns the security char for this type of database.

func (*DriverMysql) New 

func (d *DriverMysql) New(core *Core, node *ConfigNode) (DB, error)

New creates and returns a database object for mysql. It implements the interface of gdb.Driver for extra database driver installation.

func (*DriverMysql) Open 

func (d *DriverMysql) Open(config *ConfigNode) (db *sql.DB, err error)

Open creates and returns an underlying sql.DB object for mysql. Note that it converts time.Time argument to local timezone in default.

func (*DriverMysql) TableFields 

func (d *DriverMysql) TableFields(ctx context.Context, table string, schema ...string) (fields map[string]*TableField, err error)

TableFields retrieves and returns the fields' information of specified table of current schema.

The parameter `link` is optional, if given nil it automatically retrieves a raw sql connection as its link to proceed necessary sql query.

Note that it returns a map containing the field name and its corresponding fields. As a map is unsorted, the TableField struct has a "Index" field marks its sequence in the fields.

It's using cache feature to enhance the performance, which is never expired util the process restarts.

func (*DriverMysql) Tables 

func (d *DriverMysql) Tables(ctx context.Context, schema ...string) (tables []string, err error)

Tables retrieves and returns the tables of current schema. It's mainly used in cli tool chain for automatically generating the models.

type HookDeleteInput added in v2.0.5 

type HookDeleteInput struct {
	Table     string
	Condition string
	Args      []interface{}
	// contains filtered or unexported fields
}

HookDeleteInput holds the parameters for delete hook operation.

func (*HookDeleteInput) Next added in v2.0.5 

func (h *HookDeleteInput) Next(ctx context.Context) (result sql.Result, err error)

Next calls the next hook handler.

type HookFuncDelete added in v2.0.5 

type HookFuncDelete func(ctx context.Context, in *HookDeleteInput) (result sql.Result, err error)

type HookFuncInsert added in v2.0.5 

type HookFuncInsert func(ctx context.Context, in *HookInsertInput) (result sql.Result, err error)

type HookFuncSelect added in v2.0.5 

type HookFuncSelect func(ctx context.Context, in *HookSelectInput) (result Result, err error)

type HookFuncUpdate added in v2.0.5 

type HookFuncUpdate func(ctx context.Context, in *HookUpdateInput) (result sql.Result, err error)

type HookHandler added in v2.0.5 

type HookHandler struct {
	Select HookFuncSelect
	Insert HookFuncInsert
	Update HookFuncUpdate
	Delete HookFuncDelete
}

HookHandler manages all supported hook functions for Model.

type HookInsertInput added in v2.0.5 

type HookInsertInput struct {
	Table  string
	Data   List
	Option DoInsertOption
	// contains filtered or unexported fields
}

HookInsertInput holds the parameters for insert hook operation.

func (*HookInsertInput) Next added in v2.0.5 

func (h *HookInsertInput) Next(ctx context.Context) (result sql.Result, err error)

Next calls the next hook handler.

type HookSelectInput added in v2.0.5 

type HookSelectInput struct {
	Table string
	Sql   string
	Args  []interface{}
	// contains filtered or unexported fields
}

HookSelectInput holds the parameters for select hook operation. Note that, COUNT statement will also be hooked by this feature, which is usually not be interesting for upper business hook handler.

func (*HookSelectInput) Next added in v2.0.5 

func (h *HookSelectInput) Next(ctx context.Context) (result Result, err error)

Next calls the next hook handler.

type HookUpdateInput added in v2.0.5 

type HookUpdateInput struct {
	Table     string
	Data      interface{} // Data can be type of: map[string]interface{}/string. You can use type assertion on `Data`.
	Condition string
	Args      []interface{}
	// contains filtered or unexported fields
}

HookUpdateInput holds the parameters for update hook operation.

func (*HookUpdateInput) Next added in v2.0.5 

func (h *HookUpdateInput) Next(ctx context.Context) (result sql.Result, err error)

Next calls the next hook handler. 

type Link interface {
	QueryContext(ctx context.Context, sql string, args ...interface{}) (*sql.Rows, error)
	ExecContext(ctx context.Context, sql string, args ...interface{}) (sql.Result, error)
	PrepareContext(ctx context.Context, sql string) (*sql.Stmt, error)
	IsOnMaster() bool
	IsTransaction() bool
}

Link is a common database function wrapper interface. Note that, any operation using `Link` will have no SQL logging.

type List 

type List = []Map // List is type of map array.

type Map 

type Map = map[string]interface{} // Map is alias of map[string]interface{}, which is the most common usage map type.

type Model 

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

Model is core struct implementing the DAO for ORM.

func (*Model) All 

func (m *Model) All(where ...interface{}) (Result, error)

All does "SELECT FROM ..." statement for the model. It retrieves the records from table and returns the result as slice type. It returns nil if there's no record retrieved with the given conditions from table.

The optional parameter `where` is the same as the parameter of Model.Where function, see Model.Where.

func (*Model) Args 

func (m *Model) Args(args ...interface{}) *Model

Args sets custom arguments for model operation.

func (*Model) Array 

func (m *Model) Array(fieldsAndWhere ...interface{}) ([]Value, error)

Array queries and returns data values as slice from database. Note that if there are multiple columns in the result, it returns just one column values randomly.

If the optional parameter `fieldsAndWhere` is given, the fieldsAndWhere[0] is the selected fields and fieldsAndWhere[1:] is treated as where condition fields. Also see Model.Fields and Model.Where functions.

func (*Model) As 

func (m *Model) As(as string) *Model

As sets an alias name for current table.

func (*Model) Avg 

func (m *Model) Avg(column string) (float64, error)

Avg does "SELECT AVG(x) FROM ..." statement for the model.

func (*Model) Batch 

func (m *Model) Batch(batch int) *Model

Batch sets the batch operation number for the model.

func (*Model) Cache 

func (m *Model) Cache(option CacheOption) *Model

Cache sets the cache feature for the model. It caches the result of the sql, which means if there's another same sql request, it just reads and returns the result from cache, it but not committed and executed into the database.

Note that, the cache feature is disabled if the model is performing select statement on a transaction.

func (*Model) Chunk 

func (m *Model) Chunk(size int, handler ChunkHandler)

Chunk iterates the query result with given `size` and `handler` function.

func (*Model) Clone 

func (m *Model) Clone() *Model

Clone creates and returns a new model which is a clone of current model. Note that it uses deep-copy for the clone.

func (*Model) Count 

func (m *Model) Count(where ...interface{}) (int, error)

Count does "SELECT COUNT(x) FROM ..." statement for the model. The optional parameter `where` is the same as the parameter of Model.Where function, see Model.Where.

func (*Model) CountColumn 

func (m *Model) CountColumn(column string) (int, error)

CountColumn does "SELECT COUNT(x) FROM ..." statement for the model.

func (*Model) Ctx 

func (m *Model) Ctx(ctx context.Context) *Model

Ctx sets the context for current operation.

func (*Model) DB 

func (m *Model) DB(db DB) *Model

DB sets/changes the db object for current operation.

func (*Model) Data 

func (m *Model) Data(data ...interface{}) *Model

Data sets the operation data for the model. The parameter `data` can be type of string/map/gmap/slice/struct/*struct, etc. Note that, it uses shallow value copying for `data` if `data` is type of map/slice to avoid changing it inside function. Eg: Data("uid=10000") Data("uid", 10000) Data("uid=? AND name=?", 10000, "john") Data(g.Map{"uid": 10000, "name":"john"}) Data(g.Slice{g.Map{"uid": 10000, "name":"john"}, g.Map{"uid": 20000, "name":"smith"}).

func (*Model) Decrement 

func (m *Model) Decrement(column string, amount interface{}) (sql.Result, error)

Decrement decrements a column's value by a given amount. The parameter `amount` can be type of float or integer.

func (*Model) Delete 

func (m *Model) Delete(where ...interface{}) (result sql.Result, err error)

Delete does "DELETE FROM ... " statement for the model. The optional parameter `where` is the same as the parameter of Model.Where function, see Model.Where.

func (*Model) Distinct 

func (m *Model) Distinct() *Model

Distinct forces the query to only return distinct results.

func (*Model) FieldAvg 

func (m *Model) FieldAvg(column string, as ...string) *Model

FieldAvg formats and appends commonly used field `AVG(column)` to the select fields of model.

func (*Model) FieldCount 

func (m *Model) FieldCount(column string, as ...string) *Model

FieldCount formats and appends commonly used field `COUNT(column)` to the select fields of model.

func (*Model) FieldMax 

func (m *Model) FieldMax(column string, as ...string) *Model

FieldMax formats and appends commonly used field `MAX(column)` to the select fields of model.

func (*Model) FieldMin 

func (m *Model) FieldMin(column string, as ...string) *Model

FieldMin formats and appends commonly used field `MIN(column)` to the select fields of model.

func (*Model) FieldSum 

func (m *Model) FieldSum(column string, as ...string) *Model

FieldSum formats and appends commonly used field `SUM(column)` to the select fields of model.

func (*Model) Fields 

func (m *Model) Fields(fieldNamesOrMapStruct ...interface{}) *Model

Fields appends `fieldNamesOrMapStruct` to the operation fields of the model, multiple fields joined using char ','. The parameter `fieldNamesOrMapStruct` can be type of string/map/*map/struct/*struct.

Eg: Fields("id", "name", "age") Fields([]string{"id", "name", "age"}) Fields(map[string]interface{}{"id":1, "name":"john", "age":18}) Fields(User{ Id: 1, Name: "john", Age: 18}).

func (*Model) FieldsEx 

func (m *Model) FieldsEx(fieldNamesOrMapStruct ...interface{}) *Model

FieldsEx appends `fieldNamesOrMapStruct` to the excluded operation fields of the model, multiple fields joined using char ','. Note that this function supports only single table operations. The parameter `fieldNamesOrMapStruct` can be type of string/map/*map/struct/*struct.

Also see Fields.

func (*Model) FieldsExPrefix 

func (m *Model) FieldsExPrefix(prefix string, fieldNamesOrMapStruct ...interface{}) *Model

FieldsExPrefix performs as function FieldsEx but add extra prefix for each field.

func (*Model) FieldsPrefix 

func (m *Model) FieldsPrefix(prefix string, fieldNamesOrMapStruct ...interface{}) *Model

FieldsPrefix performs as function Fields but add extra prefix for each field.

func (*Model) GetCtx 

func (m *Model) GetCtx() context.Context

GetCtx returns the context for current Model. It returns `context.Background()` is there's no context previously set.

func (*Model) GetFieldsExStr 

func (m *Model) GetFieldsExStr(fields string, prefix ...string) string

GetFieldsExStr retrieves and returns fields which are not in parameter `fields` from the table, joined with char ','. The parameter `fields` specifies the fields that are excluded. The optional parameter `prefix` specifies the prefix for each field, eg: FieldsExStr("id", "u.").

func (*Model) GetFieldsStr 

func (m *Model) GetFieldsStr(prefix ...string) string

GetFieldsStr retrieves and returns all fields from the table, joined with char ','. The optional parameter `prefix` specifies the prefix for each field, eg: GetFieldsStr("u.").

func (*Model) Group 

func (m *Model) Group(groupBy ...string) *Model

Group sets the "GROUP BY" statement for the model.

func (*Model) Handler 

func (m *Model) Handler(handlers ...ModelHandler) *Model

Handler calls each of `handlers` on current Model and returns a new Model. ModelHandler is a function that handles given Model and returns a new Model that is custom modified.

func (*Model) HasField 

func (m *Model) HasField(field string) (bool, error)

HasField determine whether the field exists in the table.

func (*Model) Having 

func (m *Model) Having(having interface{}, args ...interface{}) *Model

Having sets the having statement for the model. The parameters of this function usage are as the same as function Where. See Where.

func (*Model) Hook added in v2.0.5 

func (m *Model) Hook(hook HookHandler) *Model

Hook sets the hook functions for current model.

func (*Model) Increment 

func (m *Model) Increment(column string, amount interface{}) (sql.Result, error)

Increment increments a column's value by a given amount. The parameter `amount` can be type of float or integer.

func (*Model) InnerJoin 

func (m *Model) InnerJoin(table ...string) *Model

InnerJoin does "INNER JOIN ... ON ..." statement on the model. The parameter `table` can be joined table and its joined condition, and also with its alias name。

Eg: Model("user").InnerJoin("user_detail", "user_detail.uid=user.uid") Model("user", "u").InnerJoin("user_detail", "ud", "ud.uid=u.uid") Model("user", "u").InnerJoin("SELECT xxx FROM xxx AS a", "a.uid=u.uid").

func (*Model) InnerJoinOnField 

func (m *Model) InnerJoinOnField(table, field string) *Model

InnerJoinOnField performs as InnerJoin, but it joins both tables with the same field name.

Eg: Model("order").InnerJoinOnField("user", "user_id") Model("order").InnerJoinOnField("product", "product_id").

func (*Model) Insert 

func (m *Model) Insert(data ...interface{}) (result sql.Result, err error)

Insert does "INSERT INTO ..." statement for the model. The optional parameter `data` is the same as the parameter of Model.Data function, see Model.Data.

func (*Model) InsertAndGetId 

func (m *Model) InsertAndGetId(data ...interface{}) (lastInsertId int64, err error)

InsertAndGetId performs action Insert and returns the last insert id that automatically generated.

func (*Model) InsertIgnore 

func (m *Model) InsertIgnore(data ...interface{}) (result sql.Result, err error)

InsertIgnore does "INSERT IGNORE INTO ..." statement for the model. The optional parameter `data` is the same as the parameter of Model.Data function, see Model.Data.

func (*Model) LeftJoin 

func (m *Model) LeftJoin(table ...string) *Model

LeftJoin does "LEFT JOIN ... ON ..." statement on the model. The parameter `table` can be joined table and its joined condition, and also with its alias name.

Eg: Model("user").LeftJoin("user_detail", "user_detail.uid=user.uid") Model("user", "u").LeftJoin("user_detail", "ud", "ud.uid=u.uid") Model("user", "u").LeftJoin("SELECT xxx FROM xxx AS a", "a.uid=u.uid").

func (*Model) LeftJoinOnField 

func (m *Model) LeftJoinOnField(table, field string) *Model

LeftJoinOnField performs as LeftJoin, but it joins both tables with the same field name.

Eg: Model("order").LeftJoinOnField("user", "user_id") Model("order").LeftJoinOnField("product", "product_id").

func (*Model) Limit 

func (m *Model) Limit(limit ...int) *Model

Limit sets the "LIMIT" statement for the model. The parameter `limit` can be either one or two number, if passed two number is passed, it then sets "LIMIT limit[0],limit[1]" statement for the model, or else it sets "LIMIT limit[0]" statement.

func (*Model) LockShared 

func (m *Model) LockShared() *Model

LockShared sets the lock in share mode for current operation.

func (*Model) LockUpdate 

func (m *Model) LockUpdate() *Model

LockUpdate sets the lock for update for current operation.

func (*Model) Master 

func (m *Model) Master() *Model

Master marks the following operation on master node.

func (*Model) Max 

func (m *Model) Max(column string) (float64, error)

Max does "SELECT MAX(x) FROM ..." statement for the model.

func (*Model) Min 

func (m *Model) Min(column string) (float64, error)

Min does "SELECT MIN(x) FROM ..." statement for the model.

func (*Model) Offset 

func (m *Model) Offset(offset int) *Model

Offset sets the "OFFSET" statement for the model. It only makes sense for some databases like SQLServer, PostgreSQL, etc.

func (*Model) OmitEmpty 

func (m *Model) OmitEmpty() *Model

OmitEmpty sets optionOmitEmpty option for the model, which automatically filers the data and where parameters for `empty` values.

func (*Model) OmitEmptyData 

func (m *Model) OmitEmptyData() *Model

OmitEmptyData sets optionOmitEmptyData option for the model, which automatically filers the Data parameters for `empty` values.

func (*Model) OmitEmptyWhere 

func (m *Model) OmitEmptyWhere() *Model

OmitEmptyWhere sets optionOmitEmptyWhere option for the model, which automatically filers the Where/Having parameters for `empty` values.

Eg: Where("id", []int{}).All() -> SELECT xxx FROM xxx WHERE 0=1 Where("name", "").All() -> SELECT xxx FROM xxx WHERE `name`=” OmitEmpty().Where("id", []int{}).All() -> SELECT xxx FROM xxx OmitEmpty().("name", "").All() -> SELECT xxx FROM xxx.

func (*Model) OmitNil 

func (m *Model) OmitNil() *Model

OmitNil sets optionOmitNil option for the model, which automatically filers the data and where parameters for `nil` values.

func (*Model) OmitNilData 

func (m *Model) OmitNilData() *Model

OmitNilData sets optionOmitNilData option for the model, which automatically filers the Data parameters for `nil` values.

func (*Model) OmitNilWhere 

func (m *Model) OmitNilWhere() *Model

OmitNilWhere sets optionOmitNilWhere option for the model, which automatically filers the Where/Having parameters for `nil` values.

func (*Model) OnDuplicate 

func (m *Model) OnDuplicate(onDuplicate ...interface{}) *Model

OnDuplicate sets the operations when columns conflicts occurs. In MySQL, this is used for "ON DUPLICATE KEY UPDATE" statement. The parameter `onDuplicate` can be type of string/Raw/*Raw/map/slice. Example: OnDuplicate("nickname, age") OnDuplicate("nickname", "age") 

OnDuplicate(g.Map{
    "nickname": gdb.Raw("CONCAT('name_', VALUES(`nickname`))"),
})

OnDuplicate(g.Map{
    "nickname": "passport",
}).

func (*Model) OnDuplicateEx 

func (m *Model) OnDuplicateEx(onDuplicateEx ...interface{}) *Model

OnDuplicateEx sets the excluding columns for operations when columns conflict occurs. In MySQL, this is used for "ON DUPLICATE KEY UPDATE" statement. The parameter `onDuplicateEx` can be type of string/map/slice. Example: OnDuplicateEx("passport, password") OnDuplicateEx("passport", "password") 

OnDuplicateEx(g.Map{
    "passport": "",
    "password": "",
}).

func (*Model) One 

func (m *Model) One(where ...interface{}) (Record, error)

One retrieves one record from table and returns the result as map type. It returns nil if there's no record retrieved with the given conditions from table.

The optional parameter `where` is the same as the parameter of Model.Where function, see Model.Where.

func (*Model) Order 

func (m *Model) Order(orderBy ...interface{}) *Model

Order sets the "ORDER BY" statement for the model.

Eg: Order("id desc") Order("id", "desc"). Order("id desc,name asc") Order("id desc").Order("name asc") Order(gdb.Raw("field(id, 3,1,2)")).

func (*Model) OrderAsc 

func (m *Model) OrderAsc(column string) *Model

OrderAsc sets the "ORDER BY xxx ASC" statement for the model.

func (*Model) OrderDesc 

func (m *Model) OrderDesc(column string) *Model

OrderDesc sets the "ORDER BY xxx DESC" statement for the model.

func (*Model) OrderRandom 

func (m *Model) OrderRandom() *Model

OrderRandom sets the "ORDER BY RANDOM()" statement for the model.

func (*Model) Page 

func (m *Model) Page(page, limit int) *Model

Page sets the paging number for the model. The parameter `page` is started from 1 for paging. Note that, it differs that the Limit function starts from 0 for "LIMIT" statement.

func (*Model) QuoteWord 

func (m *Model) QuoteWord(s string) string

QuoteWord checks given string `s` a word, if true it quotes `s` with security chars of the database and returns the quoted string; or else it returns `s` without any change.

The meaning of a `word` can be considered as a column name.

func (*Model) Raw 

func (m *Model) Raw(rawSql string, args ...interface{}) *Model

Raw sets current model as a raw sql model. Example: 

db.Raw("SELECT * FROM `user` WHERE `name` = ?", "john").Scan(&result)

See Core.Raw.

func (*Model) Replace 

func (m *Model) Replace(data ...interface{}) (result sql.Result, err error)

Replace does "REPLACE INTO ..." statement for the model. The optional parameter `data` is the same as the parameter of Model.Data function, see Model.Data.

func (*Model) RightJoin 

func (m *Model) RightJoin(table ...string) *Model

RightJoin does "RIGHT JOIN ... ON ..." statement on the model. The parameter `table` can be joined table and its joined condition, and also with its alias name.

Eg: Model("user").RightJoin("user_detail", "user_detail.uid=user.uid") Model("user", "u").RightJoin("user_detail", "ud", "ud.uid=u.uid") Model("user", "u").RightJoin("SELECT xxx FROM xxx AS a", "a.uid=u.uid").

func (*Model) RightJoinOnField 

func (m *Model) RightJoinOnField(table, field string) *Model

RightJoinOnField performs as RightJoin, but it joins both tables with the same field name.

Eg: Model("order").InnerJoinOnField("user", "user_id") Model("order").InnerJoinOnField("product", "product_id").

func (*Model) Safe 

func (m *Model) Safe(safe ...bool) *Model

Safe marks this model safe or unsafe. If safe is true, it clones and returns a new model object whenever the operation done, or else it changes the attribute of current model.

func (*Model) Save 

func (m *Model) Save(data ...interface{}) (result sql.Result, err error)

Save does "INSERT INTO ... ON DUPLICATE KEY UPDATE..." statement for the model. The optional parameter `data` is the same as the parameter of Model.Data function, see Model.Data.

It updates the record if there's primary or unique index in the saving data, or else it inserts a new record into the table.

func (*Model) Scan 

func (m *Model) Scan(pointer interface{}, where ...interface{}) error

Scan automatically calls Struct or Structs function according to the type of parameter `pointer`. It calls function doStruct if `pointer` is type of *struct/**struct. It calls function doStructs if `pointer` is type of *[]struct/*[]*struct.

The optional parameter `where` is the same as the parameter of Model.Where function, see Model.Where.

Note that it returns sql.ErrNoRows if the given parameter `pointer` pointed to a variable that has default value and there's no record retrieved with the given conditions from table.

Example: user := new(User) err := db.Model("user").Where("id", 1).Scan(user)

user := (*User)(nil) err := db.Model("user").Where("id", 1).Scan(&user)

users := ([]User)(nil) err := db.Model("user").Scan(&users)

users := ([]*User)(nil) err := db.Model("user").Scan(&users).

func (*Model) ScanList 

func (m *Model) ScanList(structSlicePointer interface{}, bindToAttrName string, relationAttrNameAndFields ...string) (err error)

ScanList converts `r` to struct slice which contains other complex struct attributes. Note that the parameter `listPointer` should be type of *[]struct/*[]*struct.

See Result.ScanList.

func (*Model) Schema 

func (m *Model) Schema(schema string) *Model

Schema sets the schema for current operation.

func (*Model) Sharding added in v2.0.5 

func (m *Model) Sharding(handler ShardingHandler) *Model

Sharding creates and returns a new model with sharding handler.

func (*Model) Slave 

func (m *Model) Slave() *Model

Slave marks the following operation on slave node. Note that it makes sense only if there's any slave node configured.

func (*Model) Sum 

func (m *Model) Sum(column string) (float64, error)

Sum does "SELECT SUM(x) FROM ..." statement for the model.

func (*Model) TX 

func (m *Model) TX(tx *TX) *Model

TX sets/changes the transaction for current operation.

func (*Model) TableFields 

func (m *Model) TableFields(tableStr string, schema ...string) (fields map[string]*TableField, err error)

TableFields retrieves and returns the fields' information of specified table of current schema.

Also see DriverMysql.TableFields.

func (*Model) Transaction 

func (m *Model) Transaction(ctx context.Context, f func(ctx context.Context, tx *TX) error) (err error)

Transaction wraps the transaction logic using function `f`. It rollbacks the transaction and returns the error from function `f` if it returns non-nil error. It commits the transaction and returns nil if function `f` returns nil.

Note that, you should not Commit or Rollback the transaction in function `f` as it is automatically handled by this function.

func (*Model) Union 

func (m *Model) Union(unions ...*Model) *Model

Union does "(SELECT xxx FROM xxx) UNION (SELECT xxx FROM xxx) ..." statement for the model.

func (*Model) UnionAll 

func (m *Model) UnionAll(unions ...*Model) *Model

UnionAll does "(SELECT xxx FROM xxx) UNION ALL (SELECT xxx FROM xxx) ..." statement for the model.

func (*Model) Unscoped 

func (m *Model) Unscoped() *Model

Unscoped disables the auto-update time feature for insert, update and delete options.

func (*Model) Update 

func (m *Model) Update(dataAndWhere ...interface{}) (result sql.Result, err error)

Update does "UPDATE ... " statement for the model.

If the optional parameter `dataAndWhere` is given, the dataAndWhere[0] is the updated data field, and dataAndWhere[1:] is treated as where condition fields. Also see Model.Data and Model.Where functions.

func (*Model) UpdateAndGetAffected added in v2.1.0 

func (m *Model) UpdateAndGetAffected(dataAndWhere ...interface{}) (affected int64, err error)

UpdateAndGetAffected performs update statement and returns the affected rows number.

func (*Model) Value 

func (m *Model) Value(fieldsAndWhere ...interface{}) (Value, error)

Value retrieves a specified record value from table and returns the result as interface type. It returns nil if there's no record found with the given conditions from table.

If the optional parameter `fieldsAndWhere` is given, the fieldsAndWhere[0] is the selected fields and fieldsAndWhere[1:] is treated as where condition fields. Also see Model.Fields and Model.Where functions.

func (*Model) Where 

func (m *Model) Where(where interface{}, args ...interface{}) *Model

Where sets the condition statement for the model. The parameter `where` can be type of string/map/gmap/slice/struct/*struct, etc. Note that, if it's called more than one times, multiple conditions will be joined into where statement using "AND". Eg: Where("uid=10000") Where("uid", 10000) Where("money>? AND name like ?", 99999, "vip_%") Where("uid", 1).Where("name", "john") Where("status IN (?)", g.Slice{1,2,3}) Where("age IN(?,?)", 18, 50) Where(User{ Id : 1, UserName : "john"}).

func (*Model) WhereBetween 

func (m *Model) WhereBetween(column string, min, max interface{}) *Model

WhereBetween builds `column BETWEEN min AND max` statement.

func (*Model) WhereGT 

func (m *Model) WhereGT(column string, value interface{}) *Model

WhereGT builds `column > value` statement.

func (*Model) WhereGTE 

func (m *Model) WhereGTE(column string, value interface{}) *Model

WhereGTE builds `column >= value` statement.

func (*Model) WhereIn 

func (m *Model) WhereIn(column string, in interface{}) *Model

WhereIn builds `column IN (in)` statement.

func (*Model) WhereLT 

func (m *Model) WhereLT(column string, value interface{}) *Model

WhereLT builds `column < value` statement.

func (*Model) WhereLTE 

func (m *Model) WhereLTE(column string, value interface{}) *Model

WhereLTE builds `column <= value` statement.

func (*Model) WhereLike 

func (m *Model) WhereLike(column string, like string) *Model

WhereLike builds `column LIKE like` statement.

func (*Model) WhereNot 

func (m *Model) WhereNot(column string, value interface{}) *Model

WhereNot builds `column != value` statement.

func (*Model) WhereNotBetween 

func (m *Model) WhereNotBetween(column string, min, max interface{}) *Model

WhereNotBetween builds `column NOT BETWEEN min AND max` statement.

func (*Model) WhereNotIn 

func (m *Model) WhereNotIn(column string, in interface{}) *Model

WhereNotIn builds `column NOT IN (in)` statement.

func (*Model) WhereNotLike 

func (m *Model) WhereNotLike(column string, like interface{}) *Model

WhereNotLike builds `column NOT LIKE like` statement.

func (*Model) WhereNotNull 

func (m *Model) WhereNotNull(columns ...string) *Model

WhereNotNull builds `columns[0] IS NOT NULL AND columns[1] IS NOT NULL ...` statement.

func (*Model) WhereNull 

func (m *Model) WhereNull(columns ...string) *Model

WhereNull builds `columns[0] IS NULL AND columns[1] IS NULL ...` statement.

func (*Model) WhereOr 

func (m *Model) WhereOr(where interface{}, args ...interface{}) *Model

WhereOr adds "OR" condition to the where statement.

func (*Model) WhereOrBetween 

func (m *Model) WhereOrBetween(column string, min, max interface{}) *Model

WhereOrBetween builds `column BETWEEN min AND max` statement in `OR` conditions.

func (*Model) WhereOrGT 

func (m *Model) WhereOrGT(column string, value interface{}) *Model

WhereOrGT builds `column > value` statement in `OR` conditions..

func (*Model) WhereOrGTE 

func (m *Model) WhereOrGTE(column string, value interface{}) *Model

WhereOrGTE builds `column >= value` statement in `OR` conditions..

func (*Model) WhereOrIn 

func (m *Model) WhereOrIn(column string, in interface{}) *Model

WhereOrIn builds `column IN (in)` statement in `OR` conditions.

func (*Model) WhereOrLT 

func (m *Model) WhereOrLT(column string, value interface{}) *Model

WhereOrLT builds `column < value` statement in `OR` conditions..

func (*Model) WhereOrLTE 

func (m *Model) WhereOrLTE(column string, value interface{}) *Model

WhereOrLTE builds `column <= value` statement in `OR` conditions..

func (*Model) WhereOrLike 

func (m *Model) WhereOrLike(column string, like interface{}) *Model

WhereOrLike builds `column LIKE like` statement in `OR` conditions.

func (*Model) WhereOrNotBetween 

func (m *Model) WhereOrNotBetween(column string, min, max interface{}) *Model

WhereOrNotBetween builds `column NOT BETWEEN min AND max` statement in `OR` conditions.

func (*Model) WhereOrNotIn 

func (m *Model) WhereOrNotIn(column string, in interface{}) *Model

WhereOrNotIn builds `column NOT IN (in)` statement.

func (*Model) WhereOrNotLike 

func (m *Model) WhereOrNotLike(column string, like interface{}) *Model

WhereOrNotLike builds `column NOT LIKE like` statement in `OR` conditions.

func (*Model) WhereOrNotNull 

func (m *Model) WhereOrNotNull(columns ...string) *Model

WhereOrNotNull builds `columns[0] IS NOT NULL OR columns[1] IS NOT NULL ...` statement in `OR` conditions.

func (*Model) WhereOrNull 

func (m *Model) WhereOrNull(columns ...string) *Model

WhereOrNull builds `columns[0] IS NULL OR columns[1] IS NULL ...` statement in `OR` conditions.

func (*Model) WhereOrPrefix 

func (m *Model) WhereOrPrefix(prefix string, where interface{}, args ...interface{}) *Model

WhereOrPrefix performs as WhereOr, but it adds prefix to each field in where statement. Eg: WhereOrPrefix("order", "status", "paid") => WHERE xxx OR (`order`.`status`='paid') WhereOrPrefix("order", struct{Status:"paid", "channel":"bank"}) => WHERE xxx OR (`order`.`status`='paid' AND `order`.`channel`='bank')

func (*Model) WhereOrPrefixBetween 

func (m *Model) WhereOrPrefixBetween(prefix string, column string, min, max interface{}) *Model

WhereOrPrefixBetween builds `prefix.column BETWEEN min AND max` statement in `OR` conditions.

func (*Model) WhereOrPrefixGT 

func (m *Model) WhereOrPrefixGT(prefix string, column string, value interface{}) *Model

WhereOrPrefixGT builds `prefix.column > value` statement in `OR` conditions..

func (*Model) WhereOrPrefixGTE 

func (m *Model) WhereOrPrefixGTE(prefix string, column string, value interface{}) *Model

WhereOrPrefixGTE builds `prefix.column >= value` statement in `OR` conditions..

func (*Model) WhereOrPrefixIn 

func (m *Model) WhereOrPrefixIn(prefix string, column string, in interface{}) *Model

WhereOrPrefixIn builds `prefix.column IN (in)` statement in `OR` conditions.

func (*Model) WhereOrPrefixLT 

func (m *Model) WhereOrPrefixLT(prefix string, column string, value interface{}) *Model

WhereOrPrefixLT builds `prefix.column < value` statement in `OR` conditions..

func (*Model) WhereOrPrefixLTE 

func (m *Model) WhereOrPrefixLTE(prefix string, column string, value interface{}) *Model

WhereOrPrefixLTE builds `prefix.column <= value` statement in `OR` conditions..

func (*Model) WhereOrPrefixLike 

func (m *Model) WhereOrPrefixLike(prefix string, column string, like interface{}) *Model

WhereOrPrefixLike builds `prefix.column LIKE like` statement in `OR` conditions.

func (*Model) WhereOrPrefixNotBetween 

func (m *Model) WhereOrPrefixNotBetween(prefix string, column string, min, max interface{}) *Model

WhereOrPrefixNotBetween builds `prefix.column NOT BETWEEN min AND max` statement in `OR` conditions.

func (*Model) WhereOrPrefixNotIn 

func (m *Model) WhereOrPrefixNotIn(prefix string, column string, in interface{}) *Model

WhereOrPrefixNotIn builds `prefix.column NOT IN (in)` statement.

func (*Model) WhereOrPrefixNotLike 

func (m *Model) WhereOrPrefixNotLike(prefix string, column string, like interface{}) *Model

WhereOrPrefixNotLike builds `prefix.column NOT LIKE like` statement in `OR` conditions.

func (*Model) WhereOrPrefixNotNull 

func (m *Model) WhereOrPrefixNotNull(prefix string, columns ...string) *Model

WhereOrPrefixNotNull builds `prefix.columns[0] IS NOT NULL OR prefix.columns[1] IS NOT NULL ...` statement in `OR` conditions.

func (*Model) WhereOrPrefixNull 

func (m *Model) WhereOrPrefixNull(prefix string, columns ...string) *Model

WhereOrPrefixNull builds `prefix.columns[0] IS NULL OR prefix.columns[1] IS NULL ...` statement in `OR` conditions.

func (*Model) WhereOrf 

func (m *Model) WhereOrf(format string, args ...interface{}) *Model

WhereOrf builds `OR` condition string using fmt.Sprintf and arguments. Eg: WhereOrf(`amount<? and status=%s`, "paid", 100) => WHERE xxx OR `amount`<100 and status='paid' WhereOrf(`amount<%d and status=%s`, 100, "paid") => WHERE xxx OR `amount`<100 and status='paid'

func (*Model) WherePrefix 

func (m *Model) WherePrefix(prefix string, where interface{}, args ...interface{}) *Model

WherePrefix performs as Where, but it adds prefix to each field in where statement. Eg: WherePrefix("order", "status", "paid") => WHERE `order`.`status`='paid' WherePrefix("order", struct{Status:"paid", "channel":"bank"}) => WHERE `order`.`status`='paid' AND `order`.`channel`='bank'

func (*Model) WherePrefixBetween 

func (m *Model) WherePrefixBetween(prefix string, column string, min, max interface{}) *Model

WherePrefixBetween builds `prefix.column BETWEEN min AND max` statement.

func (*Model) WherePrefixGT 

func (m *Model) WherePrefixGT(prefix string, column string, value interface{}) *Model

WherePrefixGT builds `prefix.column > value` statement.

func (*Model) WherePrefixGTE 

func (m *Model) WherePrefixGTE(prefix string, column string, value interface{}) *Model

WherePrefixGTE builds `prefix.column >= value` statement.

func (*Model) WherePrefixIn 

func (m *Model) WherePrefixIn(prefix string, column string, in interface{}) *Model

WherePrefixIn builds `prefix.column IN (in)` statement.

func (*Model) WherePrefixLT 

func (m *Model) WherePrefixLT(prefix string, column string, value interface{}) *Model

WherePrefixLT builds `prefix.column < value` statement.

func (*Model) WherePrefixLTE 

func (m *Model) WherePrefixLTE(prefix string, column string, value interface{}) *Model

WherePrefixLTE builds `prefix.column <= value` statement.

func (*Model) WherePrefixLike 

func (m *Model) WherePrefixLike(prefix string, column string, like interface{}) *Model

WherePrefixLike builds `prefix.column LIKE like` statement.

func (*Model) WherePrefixNot 

func (m *Model) WherePrefixNot(prefix string, column string, value interface{}) *Model

WherePrefixNot builds `prefix.column != value` statement.

func (*Model) WherePrefixNotBetween 

func (m *Model) WherePrefixNotBetween(prefix string, column string, min, max interface{}) *Model

WherePrefixNotBetween builds `prefix.column NOT BETWEEN min AND max` statement.

func (*Model) WherePrefixNotIn 

func (m *Model) WherePrefixNotIn(prefix string, column string, in interface{}) *Model

WherePrefixNotIn builds `prefix.column NOT IN (in)` statement.

func (*Model) WherePrefixNotLike 

func (m *Model) WherePrefixNotLike(prefix string, column string, like interface{}) *Model

WherePrefixNotLike builds `prefix.column NOT LIKE like` statement.

func (*Model) WherePrefixNotNull 

func (m *Model) WherePrefixNotNull(prefix string, columns ...string) *Model

WherePrefixNotNull builds `prefix.columns[0] IS NOT NULL AND prefix.columns[1] IS NOT NULL ...` statement.

func (*Model) WherePrefixNull 

func (m *Model) WherePrefixNull(prefix string, columns ...string) *Model

WherePrefixNull builds `prefix.columns[0] IS NULL AND prefix.columns[1] IS NULL ...` statement.

func (*Model) WherePri 

func (m *Model) WherePri(where interface{}, args ...interface{}) *Model

WherePri does the same logic as Model.Where except that if the parameter `where` is a single condition like int/string/float/slice, it treats the condition as the primary key value. That is, if primary key is "id" and given `where` parameter as "123", the WherePri function treats the condition as "id=123", but Model.Where treats the condition as string "123".

func (*Model) Wheref 

func (m *Model) Wheref(format string, args ...interface{}) *Model

Wheref builds condition string using fmt.Sprintf and arguments. Note that if the number of `args` is more than the placeholder in `format`, the extra `args` will be used as the where condition arguments of the Model. Eg: Wheref(`amount<? and status=%s`, "paid", 100) => WHERE `amount`<100 and status='paid' Wheref(`amount<%d and status=%s`, 100, "paid") => WHERE `amount`<100 and status='paid'

func (*Model) With 

func (m *Model) With(objects ...interface{}) *Model

With creates and returns an ORM model based on metadata of given object. It also enables model association operations feature on given `object`. It can be called multiple times to add one or more objects to model and enable their mode association operations feature. For example, if given struct definition: 

type User struct {
	 gmeta.Meta `orm:"table:user"`
	 Id         int           `json:"id"`
	 Name       string        `json:"name"`
	 UserDetail *UserDetail   `orm:"with:uid=id"`
	 UserScores []*UserScores `orm:"with:uid=id"`
}

We can enable model association operations on attribute `UserDetail` and `UserScores` by: 

db.With(User{}.UserDetail).With(User{}.UserDetail).Scan(xxx)

Or: 

db.With(UserDetail{}).With(UserDetail{}).Scan(xxx)

Or: 

db.With(UserDetail{}, UserDetail{}).Scan(xxx)

func (*Model) WithAll 

func (m *Model) WithAll() *Model

WithAll enables model association operations on all objects that have "with" tag in the struct.

type ModelHandler 

type ModelHandler func(m *Model) *Model

ModelHandler is a function that handles given Model and returns a new Model that is custom modified.

type ModelWhereHolder 

type ModelWhereHolder struct {
	Type     string        // Type of this holder.
	Operator int           // Operator for this holder.
	Where    interface{}   // Where parameter, which can commonly be type of string/map/struct.
	Args     []interface{} // Arguments for where parameter.
	Prefix   string        // Field prefix, eg: "user.", "order.".
}

ModelWhereHolder is the holder for where condition preparing.

type Raw 

type Raw string // Raw is a raw sql that will not be treated as argument but as a direct sql part.

type Record 

type Record map[string]Value // Record is the row record of the table.

func (Record) GMap 

func (r Record) GMap() *gmap.StrAnyMap

GMap converts `r` to a gmap.

func (Record) IsEmpty 

func (r Record) IsEmpty() bool

IsEmpty checks and returns whether `r` is empty.

func (Record) Json 

func (r Record) Json() string

Json converts `r` to JSON format content.

func (Record) Map 

func (r Record) Map() Map

Map converts `r` to map[string]interface{}.

func (Record) Struct 

func (r Record) Struct(pointer interface{}) error

Struct converts `r` to a struct. Note that the parameter `pointer` should be type of *struct/**struct.

Note that it returns sql.ErrNoRows if `r` is empty.

func (Record) Xml 

func (r Record) Xml(rootTag ...string) string

Xml converts `r` to XML format content.

type Result 

type Result []Record // Result is the row record array.

func (Result) Array 

func (r Result) Array(field ...string) []Value

Array retrieves and returns specified column values as slice. The parameter `field` is optional is the column field is only one. The default `field` is the first field name of the first item in `Result` if parameter `field` is not given.

func (Result) Chunk 

func (r Result) Chunk(size int) []Result

Chunk splits a Result into multiple Results, the size of each array is determined by `size`. The last chunk may contain less than size elements.

func (Result) IsEmpty 

func (r Result) IsEmpty() bool

IsEmpty checks and returns whether `r` is empty.

func (Result) Json 

func (r Result) Json() string

Json converts `r` to JSON format content.

func (Result) Len 

func (r Result) Len() int

Len returns the length of result list.

func (Result) List 

func (r Result) List() List

List converts `r` to a List.

func (Result) MapKeyInt 

func (r Result) MapKeyInt(key string) map[int]Map

MapKeyInt converts `r` to a map[int]Map of which key is specified by `key`.

func (Result) MapKeyStr 

func (r Result) MapKeyStr(key string) map[string]Map

MapKeyStr converts `r` to a map[string]Map of which key is specified by `key`.

func (Result) MapKeyUint 

func (r Result) MapKeyUint(key string) map[uint]Map

MapKeyUint converts `r` to a map[uint]Map of which key is specified by `key`.

func (Result) MapKeyValue 

func (r Result) MapKeyValue(key string) map[string]Value

MapKeyValue converts `r` to a map[string]Value of which key is specified by `key`. Note that the item value may be type of slice.

func (Result) RecordKeyInt 

func (r Result) RecordKeyInt(key string) map[int]Record

RecordKeyInt converts `r` to a map[int]Record of which key is specified by `key`.

func (Result) RecordKeyStr 

func (r Result) RecordKeyStr(key string) map[string]Record

RecordKeyStr converts `r` to a map[string]Record of which key is specified by `key`.

func (Result) RecordKeyUint 

func (r Result) RecordKeyUint(key string) map[uint]Record

RecordKeyUint converts `r` to a map[uint]Record of which key is specified by `key`.

func (Result) ScanList 

func (r Result) ScanList(structSlicePointer interface{}, bindToAttrName string, relationAttrNameAndFields ...string) (err error)

ScanList converts `r` to struct slice which contains other complex struct attributes. Note that the parameter `structSlicePointer` should be type of *[]struct/*[]*struct.

Usage example 1: Normal attribute struct relation: 

type EntityUser struct {
	   Uid  int
	   Name string
}

type EntityUserDetail struct {
	   Uid     int
	   Address string
}

type EntityUserScores struct {
	   Id     int
	   Uid    int
	   Score  int
	   Course string
}

type Entity struct {
    User       *EntityUser
	   UserDetail *EntityUserDetail
	   UserScores []*EntityUserScores
}

var users []*Entity ScanList(&users, "User") ScanList(&users, "User", "uid") ScanList(&users, "UserDetail", "User", "uid:Uid") ScanList(&users, "UserScores", "User", "uid:Uid") ScanList(&users, "UserScores", "User", "uid")

Usage example 2: Embedded attribute struct relation: 

type EntityUser struct {
	   Uid  int
	   Name string
}

type EntityUserDetail struct {
	   Uid     int
	   Address string
}

type EntityUserScores struct {
	   Id    int
	   Uid   int
	   Score int
}

type Entity struct {
	   EntityUser
	   UserDetail EntityUserDetail
	   UserScores []EntityUserScores
}

var users []*Entity ScanList(&users) ScanList(&users, "UserDetail", "uid") ScanList(&users, "UserScores", "uid")

The parameters "User/UserDetail/UserScores" in the example codes specify the target attribute struct that current result will be bound to.

The "uid" in the example codes is the table field name of the result, and the "Uid" is the relational struct attribute name - not the attribute name of the bound to target. In the example codes, it's attribute name "Uid" of "User" of entity "Entity". It automatically calculates the HasOne/HasMany relationship with given `relation` parameter.

See the example or unit testing cases for clear understanding for this function.

func (Result) Size 

func (r Result) Size() int

Size is alias of function Len.

func (Result) Structs 

func (r Result) Structs(pointer interface{}) (err error)

Structs converts `r` to struct slice. Note that the parameter `pointer` should be type of *[]struct/*[]*struct.

func (Result) Xml 

func (r Result) Xml(rootTag ...string) string

Xml converts `r` to XML format content.

type Schema 

type Schema struct {
	DB
}

Schema is a schema object from which it can then create a Model.

type ShardingHandler added in v2.0.5 

type ShardingHandler func(ctx context.Context, in ShardingInput) (out *ShardingOutput, err error)

ShardingHandler is a custom function for custom sharding table and schema for DB operation.

type ShardingInput added in v2.0.5 

type ShardingInput struct {
	Table         string           // Current operation table name.
	Schema        string           // Current operation schema, usually empty string which means uses default schema from configuration.
	OperationData map[string]Value // Accurate readonly key-value data pairs from INSERT/UPDATE statement.
	ConditionData map[string]Value // Accurate readonly key-value condition pairs from SELECT/UPDATE/DELETE statement.
}

ShardingInput is input parameters for custom sharding handler.

type ShardingOutput added in v2.0.5 

type ShardingOutput struct {
	Table  string // New table name for current operation. Use empty string for no changes of table name.
	Schema string // New schema name for current operation. Use empty string for using default schema from configuration.
}

ShardingOutput is output parameters for custom sharding handler.

type Sql 

type Sql struct {
	Sql           string        // SQL string(may contain reserved char '?').
	Type          string        // SQL operation type.
	Args          []interface{} // Arguments for this sql.
	Format        string        // Formatted sql which contains arguments in the sql.
	Error         error         // Execution result.
	Start         int64         // Start execution timestamp in milliseconds.
	End           int64         // End execution timestamp in milliseconds.
	Group         string        // Group is the group name of the configuration that the sql is executed from.
	IsTransaction bool          // IsTransaction marks whether this sql is executed in transaction.
	RowsAffected  int64         // RowsAffected marks retrieved or affected number with current sql statement.
}

Sql is the sql recording struct.

type SqlResult 

type SqlResult struct {
	Result   sql.Result
	Affected int64
}

SqlResult is execution result for sql operations. It also supports batch operation result for rowsAffected.

func (*SqlResult) LastInsertId 

func (r *SqlResult) LastInsertId() (int64, error)

LastInsertId returns the integer generated by the database in response to a command. Typically, this will be from an "auto increment" column when inserting a new row. Not all databases support this feature, and the syntax of such statements varies. Also, See sql.Result.

func (*SqlResult) MustGetAffected 

func (r *SqlResult) MustGetAffected() int64

MustGetAffected returns the affected rows count, if any error occurs, it panics.

func (*SqlResult) MustGetInsertId 

func (r *SqlResult) MustGetInsertId() int64

MustGetInsertId returns the last insert id, if any error occurs, it panics.

func (*SqlResult) RowsAffected 

func (r *SqlResult) RowsAffected() (int64, error)

RowsAffected returns the number of rows affected by an update, insert, or delete. Not every database or database driver may support this. Also, See sql.Result.

type Stmt 

type Stmt struct {
	*sql.Stmt
	// contains filtered or unexported fields
}

Stmt is a prepared statement. A Stmt is safe for concurrent use by multiple goroutines.

If a Stmt is prepared on a Tx or Conn, it will be bound to a single underlying connection forever. If the Tx or Conn closes, the Stmt will become unusable and all operations will return an error. If a Stmt is prepared on a DB, it will remain usable for the lifetime of the DB. When the Stmt needs to execute on a new underlying connection, it will prepare itself on the new connection automatically.

func (*Stmt) Close 

func (s *Stmt) Close() error

Close closes the statement.

func (*Stmt) Exec 

func (s *Stmt) Exec(args ...interface{}) (sql.Result, error)

Exec executes a prepared statement with the given arguments and returns a Result summarizing the effect of the statement.

func (*Stmt) ExecContext 

func (s *Stmt) ExecContext(ctx context.Context, args ...interface{}) (sql.Result, error)

ExecContext executes a prepared statement with the given arguments and returns a Result summarizing the effect of the statement.

func (*Stmt) Query 

func (s *Stmt) Query(args ...interface{}) (*sql.Rows, error)

Query executes a prepared query statement with the given arguments and returns the query results as a *Rows.

func (*Stmt) QueryContext 

func (s *Stmt) QueryContext(ctx context.Context, args ...interface{}) (*sql.Rows, error)

QueryContext executes a prepared query statement with the given arguments and returns the query results as a *Rows.

func (*Stmt) QueryRow 

func (s *Stmt) QueryRow(args ...interface{}) *sql.Row

QueryRow executes a prepared query statement with the given arguments. If an error occurs during the execution of the statement, that error will be returned by a call to Scan on the returned *Row, which is always non-nil. If the query selects no rows, the *Row's Scan will return ErrNoRows. Otherwise, the *Row's Scan scans the first selected row and discards the rest.

Example usage: 

var name string
err := nameByUseridStmt.QueryRow(id).Scan(&name)

func (*Stmt) QueryRowContext 

func (s *Stmt) QueryRowContext(ctx context.Context, args ...interface{}) *sql.Row

QueryRowContext executes a prepared query statement with the given arguments. If an error occurs during the execution of the statement, that error will be returned by a call to Scan on the returned *Row, which is always non-nil. If the query selects no rows, the *Row's Scan will return ErrNoRows. Otherwise, the *Row's Scan scans the first selected row and discards the rest.

type TX 

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

TX is the struct for transaction management.

func TXFromCtx 

func TXFromCtx(ctx context.Context, group string) *TX

TXFromCtx retrieves and returns transaction object from context. It is usually used in nested transaction feature, and it returns nil if it is not set previously.

func (*TX) Begin 

func (tx *TX) Begin() error

Begin starts a nested transaction procedure.

func (*TX) Commit 

func (tx *TX) Commit() error

Commit commits current transaction. Note that it releases previous saved transaction point if it's in a nested transaction procedure, or else it commits the hole transaction.

func (*TX) Ctx 

func (tx *TX) Ctx(ctx context.Context) *TX

Ctx sets the context for current transaction.

func (*TX) Delete 

func (tx *TX) Delete(table string, condition interface{}, args ...interface{}) (sql.Result, error)

Delete does "DELETE FROM ... " statement for the table.

The parameter `condition` can be type of string/map/gmap/slice/struct/*struct, etc. It is commonly used with parameter `args`. Eg: "uid=10000", "uid", 10000 "money>? AND name like ?", 99999, "vip_%" "status IN (?)", g.Slice{1,2,3} "age IN(?,?)", 18, 50 User{ Id : 1, UserName : "john"}.

func (*TX) Exec 

func (tx *TX) Exec(sql string, args ...interface{}) (sql.Result, error)

Exec does none query operation on transaction. See Core.Exec.

func (*TX) GetAll 

func (tx *TX) GetAll(sql string, args ...interface{}) (Result, error)

GetAll queries and returns data records from database.

func (*TX) GetCount 

func (tx *TX) GetCount(sql string, args ...interface{}) (int, error)

GetCount queries and returns the count from database.

func (*TX) GetOne 

func (tx *TX) GetOne(sql string, args ...interface{}) (Record, error)

GetOne queries and returns one record from database.

func (*TX) GetScan 

func (tx *TX) GetScan(pointer interface{}, sql string, args ...interface{}) error

GetScan queries one or more records from database and converts them to given struct or struct array.

If parameter `pointer` is type of struct pointer, it calls GetStruct internally for the conversion. If parameter `pointer` is type of slice, it calls GetStructs internally for conversion.

func (*TX) GetStruct 

func (tx *TX) GetStruct(obj interface{}, sql string, args ...interface{}) error

GetStruct queries one record from database and converts it to given struct. The parameter `pointer` should be a pointer to struct.

func (*TX) GetStructs 

func (tx *TX) GetStructs(objPointerSlice interface{}, sql string, args ...interface{}) error

GetStructs queries records from database and converts them to given struct. The parameter `pointer` should be type of struct slice: []struct/[]*struct.

func (*TX) GetValue 

func (tx *TX) GetValue(sql string, args ...interface{}) (Value, error)

GetValue queries and returns the field value from database. The sql should query only one field from database, or else it returns only one field of the result.

func (*TX) Insert 

func (tx *TX) Insert(table string, data interface{}, batch ...int) (sql.Result, error)

Insert does "INSERT INTO ..." statement for the table. If there's already one unique record of the data in the table, it returns error.

The parameter `data` can be type of map/gmap/struct/*struct/[]map/[]struct, etc. Eg: Data(g.Map{"uid": 10000, "name":"john"}) Data(g.Slice{g.Map{"uid": 10000, "name":"john"}, g.Map{"uid": 20000, "name":"smith"})

The parameter `batch` specifies the batch operation count when given data is slice.

func (*TX) InsertAndGetId 

func (tx *TX) InsertAndGetId(table string, data interface{}, batch ...int) (int64, error)

InsertAndGetId performs action Insert and returns the last insert id that automatically generated.

func (*TX) InsertIgnore 

func (tx *TX) InsertIgnore(table string, data interface{}, batch ...int) (sql.Result, error)

InsertIgnore does "INSERT IGNORE INTO ..." statement for the table. If there's already one unique record of the data in the table, it ignores the inserting.

The parameter `data` can be type of map/gmap/struct/*struct/[]map/[]struct, etc. Eg: Data(g.Map{"uid": 10000, "name":"john"}) Data(g.Slice{g.Map{"uid": 10000, "name":"john"}, g.Map{"uid": 20000, "name":"smith"})

The parameter `batch` specifies the batch operation count when given data is slice.

func (*TX) IsClosed 

func (tx *TX) IsClosed() bool

IsClosed checks and returns this transaction has already been committed or rolled back.

func (*TX) Model 

func (tx *TX) Model(tableNameQueryOrStruct ...interface{}) *Model

Model acts like Core.Model except it operates on transaction. See Core.Model.

func (*TX) Prepare 

func (tx *TX) Prepare(sql string) (*Stmt, error)

Prepare creates a prepared statement for later queries or executions. Multiple queries or executions may be run concurrently from the returned statement. The caller must call the statement's Close method when the statement is no longer needed.

func (*TX) Query 

func (tx *TX) Query(sql string, args ...interface{}) (result Result, err error)

Query does query operation on transaction. See Core.Query.

func (*TX) Raw 

func (tx *TX) Raw(rawSql string, args ...interface{}) *Model

func (*TX) Replace 

func (tx *TX) Replace(table string, data interface{}, batch ...int) (sql.Result, error)

Replace does "REPLACE INTO ..." statement for the table. If there's already one unique record of the data in the table, it deletes the record and inserts a new one.

The parameter `data` can be type of map/gmap/struct/*struct/[]map/[]struct, etc. Eg: Data(g.Map{"uid": 10000, "name":"john"}) Data(g.Slice{g.Map{"uid": 10000, "name":"john"}, g.Map{"uid": 20000, "name":"smith"})

The parameter `data` can be type of map/gmap/struct/*struct/[]map/[]struct, etc. If given data is type of slice, it then does batch replacing, and the optional parameter `batch` specifies the batch operation count.

func (*TX) Rollback 

func (tx *TX) Rollback() error

Rollback aborts current transaction. Note that it aborts current transaction if it's in a nested transaction procedure, or else it aborts the hole transaction.

func (*TX) RollbackTo 

func (tx *TX) RollbackTo(point string) error

RollbackTo performs `ROLLBACK TO SAVEPOINT xxx` SQL statement that rollbacks to specified saved transaction. The parameter `point` specifies the point name that was saved previously.

func (*TX) Save 

func (tx *TX) Save(table string, data interface{}, batch ...int) (sql.Result, error)

Save does "INSERT INTO ... ON DUPLICATE KEY UPDATE..." statement for the table. It updates the record if there's primary or unique index in the saving data, or else it inserts a new record into the table.

The parameter `data` can be type of map/gmap/struct/*struct/[]map/[]struct, etc. Eg: Data(g.Map{"uid": 10000, "name":"john"}) Data(g.Slice{g.Map{"uid": 10000, "name":"john"}, g.Map{"uid": 20000, "name":"smith"})

If given data is type of slice, it then does batch saving, and the optional parameter `batch` specifies the batch operation count.

func (*TX) SavePoint 

func (tx *TX) SavePoint(point string) error

SavePoint performs `SAVEPOINT xxx` SQL statement that saves transaction at current point. The parameter `point` specifies the point name that will be saved to server.

func (*TX) Transaction 

func (tx *TX) Transaction(ctx context.Context, f func(ctx context.Context, tx *TX) error) (err error)

Transaction wraps the transaction logic using function `f`. It rollbacks the transaction and returns the error from function `f` if it returns non-nil error. It commits the transaction and returns nil if function `f` returns nil.

Note that, you should not Commit or Rollback the transaction in function `f` as it is automatically handled by this function.

func (*TX) Update 

func (tx *TX) Update(table string, data interface{}, condition interface{}, args ...interface{}) (sql.Result, error)

Update does "UPDATE ... " statement for the table.

The parameter `data` can be type of string/map/gmap/struct/*struct, etc. Eg: "uid=10000", "uid", 10000, g.Map{"uid": 10000, "name":"john"}

The parameter `condition` can be type of string/map/gmap/slice/struct/*struct, etc. It is commonly used with parameter `args`. Eg: "uid=10000", "uid", 10000 "money>? AND name like ?", 99999, "vip_%" "status IN (?)", g.Slice{1,2,3} "age IN(?,?)", 18, 50 User{ Id : 1, UserName : "john"}.

func (*TX) With 

func (tx *TX) With(object interface{}) *Model

With acts like Core.With except it operates on transaction. See Core.With.

type TableField 

type TableField struct {
	Index   int         // For ordering purpose as map is unordered.
	Name    string      // Field name.
	Type    string      // Field type.
	Null    bool        // Field can be null or not.
	Key     string      // The index information(empty if it's not an index).
	Default interface{} // Default value for the field.
	Extra   string      // Extra information.
	Comment string      // Field comment.
}

TableField is the struct for table field.

type Value 

type Value = *gvar.Var // Value is the field value type.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.