gdb

package
v1.16.8 Latest Latest
Warning

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

 Go to latest Published: Apr 28, 2022 License: MIT Imports: 45 Imported by: 102

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 (
	OrmTagForStruct    = "orm"
	OrmTagForUnique    = "unique"
	OrmTagForPrimary   = "primary"
	OrmTagForTable     = "table"
	OrmTagForWith      = "with"
	OrmTagForWithWhere = "where"
	OrmTagForWithOrder = "order"
)
View Source 
const (
	DefaultGroupName = "default" // Default group name.
)

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 ConvertDataForTableRecord added in v1.14.0 

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

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

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

func DataToMapDeep added in v1.11.6 

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 added in v1.12.0 

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 added in v1.11.6 

func GetInsertOperationByOption(option int) string

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

func GetPrimaryKey added in v1.10.1 

func GetPrimaryKey(pointer interface{}) (string, error)

GetPrimaryKey retrieves and returns primary key field name from given struct.

func GetPrimaryKeyCondition added in v1.10.1 

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 GetWhereConditionOfStruct 

func GetWhereConditionOfStruct(pointer interface{}) (where string, args []interface{}, err error)

GetWhereConditionOfStruct returns the where condition sql and arguments by given struct pointer. This function automatically retrieves primary or unique field and its attribute value as condition.

func IsConfigured added in v1.13.6 

func IsConfigured() bool

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

func ListItemValues added in v1.13.2 

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 added in v1.13.3 

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 added in v1.11.6 

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 WithTX added in v1.16.0 

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

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

Types

type ChunkHandler added in v1.16.5 

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 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.
	CtxStrict            bool          `json:"ctxStrict"`            // (Optional) Strictly require context input for all database operations.
}

ConfigNode is configuration for one node.

func (*ConfigNode) String 

func (node *ConfigNode) String() string

String returns the node as string.

type Core added in v1.11.6 

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

Core is the base struct for database management.

func (*Core) Begin added in v1.11.6 

func (c *Core) Begin() (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 added in v1.16.6 

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) Ctx added in v1.14.6 

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 added in v1.11.6 

func (c *Core) Delete(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 added in v1.16.3 

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

DoCommit is a hook function, which deals with the sql string 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) DoDelete added in v1.11.6 

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 added in v1.11.6 

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) DoGetAll added in v1.11.6 

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

DoGetAll queries and returns data records from database.

func (*Core) DoInsert added in v1.11.6 

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 added in v1.11.6 

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

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

func (*Core) DoQuery added in v1.11.6 

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

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

func (*Core) DoUpdate added in v1.11.6 

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 call it manually.

func (*Core) Exec added in v1.11.6 

func (c *Core) Exec(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 added in v1.11.6 

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

GetAll queries and returns data records from database.

func (*Core) GetArray added in v1.11.6 

func (c *Core) GetArray(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 added in v1.11.6 

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

GetCache returns the internal cache object.

func (*Core) GetChars added in v1.11.6 

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

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

func (*Core) GetConfig added in v1.14.1 

func (c *Core) GetConfig() *ConfigNode

GetConfig returns the current used node configuration.

func (*Core) GetCore added in v1.16.0 

func (c *Core) GetCore() *Core

GetCore returns the underlying *Core object.

func (*Core) GetCount added in v1.11.6 

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

GetCount queries and returns the count from database.

func (*Core) GetCtx added in v1.14.6 

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 added in v1.15.2 

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

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

func (*Core) GetDebug added in v1.11.6 

func (c *Core) GetDebug() bool

GetDebug returns the debug value.

func (*Core) GetDryRun added in v1.12.2 

func (c *Core) GetDryRun() bool

GetDryRun returns the DryRun value. Deprecated, use GetConfig instead.

func (*Core) GetGroup added in v1.12.2 

func (c *Core) GetGroup() string

GetGroup returns the group string configured.

func (*Core) GetLogger added in v1.11.6 

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

GetLogger returns the (logger) of the orm.

func (*Core) GetOne added in v1.11.6 

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

GetOne queries and returns one record from database.

func (*Core) GetPrefix added in v1.11.6 

func (c *Core) GetPrefix() string

GetPrefix returns the table prefix string configured. Deprecated, use GetConfig instead.

func (*Core) GetScan added in v1.11.6 

func (c *Core) 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 (*Core) GetSchema added in v1.11.6 

func (c *Core) GetSchema() string

GetSchema returns the schema configured.

func (*Core) GetStruct added in v1.11.6 

func (c *Core) GetStruct(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 added in v1.11.6 

func (c *Core) GetStructs(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 added in v1.11.6 

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

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

func (*Core) HasTable added in v1.13.3 

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

HasTable determine whether the table name exists in the database.

func (*Core) Insert added in v1.11.6 

func (c *Core) 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 (*Core) InsertAndGetId added in v1.16.0 

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

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

func (*Core) InsertIgnore added in v1.11.6 

func (c *Core) 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 (*Core) MarshalJSON added in v1.11.6 

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 added in v1.11.6 

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 added in v1.11.6 

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 added in v1.11.6 

func (c *Core) PingMaster() error

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

func (*Core) PingSlave added in v1.11.6 

func (c *Core) PingSlave() error

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

func (*Core) Prepare added in v1.11.6 

func (c *Core) Prepare(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 added in v1.11.6 

func (c *Core) Query(sql string, args ...interface{}) (rows *sql.Rows, 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 added in v1.11.6 

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 added in v1.11.6 

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 added in v1.11.6 

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

QuoteWord checks given string `s` a word, if true quotes it with security chars of the database and returns the quoted string; or else return `s` without any change. The meaning of a `word` can be considered as a column name.

func (*Core) Raw added in v1.16.3 

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 added in v1.11.6 

func (c *Core) 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 (*Core) Save added in v1.11.6 

func (c *Core) 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 (*Core) Schema added in v1.11.6 

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

Schema creates and returns a schema.

func (*Core) SetDebug added in v1.11.6 

func (c *Core) SetDebug(debug bool)

SetDebug enables/disables the debug mode.

func (*Core) SetDryRun added in v1.12.2 

func (c *Core) SetDryRun(enabled bool)

SetDryRun enables/disables the DryRun feature. Deprecated, use GetConfig instead.

func (*Core) SetLogger added in v1.11.6 

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

SetLogger sets the logger for orm.

func (*Core) SetMaxConnLifeTime added in v1.15.6 

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 added in v1.11.6 

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 added in v1.11.6 

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) SetSchema added in v1.11.6 

func (c *Core) SetSchema(schema string)

SetSchema changes the schema for this database connection object. Importantly note that when schema configuration changed for the database, it affects all operations on the database object in the future.

func (*Core) Slave added in v1.11.6 

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) Table added in v1.11.6 

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

Table is alias of Core.Model. See Core.Model. Deprecated, use Model instead.

func (*Core) TableFields added in v1.11.6 

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 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.

It does nothing in default.

func (*Core) Tables added in v1.11.6 

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 added in v1.12.3 

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 added in v1.16.3 

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

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

func (*Core) UnionAll added in v1.16.3 

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

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

func (*Core) Update added in v1.11.6 

func (c *Core) 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 (*Core) With added in v1.15.4 

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

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

type Counter added in v1.14.6 

type Counter struct {
	Field string
	Value float64
}

Counter is the type for update count.

type DB 

type DB interface {

	// Table function is deprecated, use Model instead.
	// The DB interface is designed not only for
	// relational databases but also for NoSQL databases in the future. The name
	// "Table" is not proper for that purpose any more.
	// Also see Core.Table.
	// Deprecated.
	Table(tableNameOrStruct ...interface{}) *Model

	// 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 meta data 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 this 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(sql string, args ...interface{}) (*sql.Rows, error) // See Core.Query.
	Exec(sql string, args ...interface{}) (sql.Result, error) // See Core.Exec.
	Prepare(sql string, execOnMaster ...bool) (*Stmt, error)  // See Core.Prepare.

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

	DoGetAll(ctx context.Context, link Link, sql string, args ...interface{}) (result Result, err error)                                           // See Core.DoGetAll.
	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{}) (rows *sql.Rows, err error)                                           // See Core.DoQuery.
	DoExec(ctx context.Context, link Link, sql string, args ...interface{}) (result sql.Result, err error)                                         // See Core.DoExec.
	DoCommit(ctx context.Context, link Link, sql string, args []interface{}) (newSql string, newArgs []interface{}, err error)                     // See Core.DoCommit.
	DoPrepare(ctx context.Context, link Link, sql string) (*Stmt, error)                                                                           // See Core.DoPrepare.

	GetAll(sql string, args ...interface{}) (Result, error)                // See Core.GetAll.
	GetOne(sql string, args ...interface{}) (Record, error)                // See Core.GetOne.
	GetValue(sql string, args ...interface{}) (Value, error)               // See Core.GetValue.
	GetArray(sql string, args ...interface{}) ([]Value, error)             // See Core.GetArray.
	GetCount(sql string, args ...interface{}) (int, error)                 // See Core.GetCount.
	GetScan(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() (*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.
	SetSchema(schema string)            // See Core.SetSchema.
	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.
	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 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(group ...string) (db DB, err error)

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

type DoInsertOption added in v1.16.3 

type DoInsertOption struct {
	OnDuplicateStr string
	OnDuplicateMap map[string]interface{}
	InsertOption   int // Insert operation.
	BatchCount     int // Batch count for batch inserting.
}

DoInsertOption is the input struct for function DoInsert.

type Driver added in v1.11.6 

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 DriverMssql added in v1.11.6 

type DriverMssql struct {
	*Core
}

DriverMssql is the driver for SQL server database.

func (*DriverMssql) DoCommit added in v1.16.3 

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

DoCommit deals with the sql string before commits it to underlying sql driver.

func (*DriverMssql) DoInsert added in v1.16.5 

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

DoInsert is not supported in mssql. 

func (d *DriverMssql) FilteredLink() string

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

func (*DriverMssql) GetChars added in v1.11.6 

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

GetChars returns the security char for this type of database.

func (*DriverMssql) New added in v1.11.6 

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

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

func (*DriverMssql) Open added in v1.11.6 

func (d *DriverMssql) Open(config *ConfigNode) (*sql.DB, error)

Open creates and returns a underlying sql.DB object for mssql.

func (*DriverMssql) TableFields added in v1.11.6 

func (d *DriverMssql) 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.

Also see DriverMysql.TableFields.

func (*DriverMssql) Tables added in v1.11.6 

func (d *DriverMssql) 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 DriverMysql added in v1.11.6 

type DriverMysql struct {
	*Core
}

DriverMysql is the driver for mysql database.

func (*DriverMysql) DoCommit added in v1.16.3 

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

DoCommit 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 added in v1.11.6 

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

GetChars returns the security char for this type of database.

func (*DriverMysql) New added in v1.11.6 

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 added in v1.11.6 

func (d *DriverMysql) Open(config *ConfigNode) (*sql.DB, 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 added in v1.11.6 

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 added in v1.11.6 

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 DriverOracle added in v1.11.6 

type DriverOracle struct {
	*Core
}

DriverOracle is the driver for oracle database.

func (*DriverOracle) DoCommit added in v1.16.3 

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

DoCommit deals with the sql string before commits it to underlying sql driver.

func (*DriverOracle) DoInsert added in v1.11.6 

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

DoInsert inserts or updates data for 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 (d *DriverOracle) FilteredLink() string

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

func (*DriverOracle) GetChars added in v1.11.6 

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

GetChars returns the security char for this type of database.

func (*DriverOracle) New added in v1.11.6 

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

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

func (*DriverOracle) Open added in v1.11.6 

func (d *DriverOracle) Open(config *ConfigNode) (*sql.DB, error)

Open creates and returns a underlying sql.DB object for oracle.

func (*DriverOracle) TableFields added in v1.11.6 

func (d *DriverOracle) 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.

Also see DriverMysql.TableFields.

func (*DriverOracle) Tables added in v1.11.6 

func (d *DriverOracle) 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. Note that it ignores the parameter `schema` in oracle database, as it is not necessary.

type DriverPgsql added in v1.11.6 

type DriverPgsql struct {
	*Core
}

DriverPgsql is the driver for postgresql database.

func (*DriverPgsql) DoCommit added in v1.16.3 

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

DoCommit deals with the sql string before commits it to underlying sql driver.

func (*DriverPgsql) DoInsert added in v1.16.5 

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

DoInsert is not supported in pgsql. 

func (d *DriverPgsql) FilteredLink() string

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

func (*DriverPgsql) GetChars added in v1.11.6 

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

GetChars returns the security char for this type of database.

func (*DriverPgsql) New added in v1.11.6 

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

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

func (*DriverPgsql) Open added in v1.11.6 

func (d *DriverPgsql) Open(config *ConfigNode) (*sql.DB, error)

Open creates and returns a underlying sql.DB object for pgsql.

func (*DriverPgsql) TableFields added in v1.11.6 

func (d *DriverPgsql) 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.

Also see DriverMysql.TableFields.

func (*DriverPgsql) Tables added in v1.11.6 

func (d *DriverPgsql) 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 DriverSqlite added in v1.11.6 

type DriverSqlite struct {
	*Core
}

DriverSqlite is the driver for sqlite database.

func (*DriverSqlite) DoCommit added in v1.16.3 

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

DoCommit deals with the sql string before commits it to underlying sql driver.

func (*DriverSqlite) DoInsert added in v1.16.5 

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

DoInsert is not supported in sqlite. 

func (d *DriverSqlite) FilteredLink() string

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

func (*DriverSqlite) GetChars added in v1.11.6 

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

GetChars returns the security char for this type of database.

func (*DriverSqlite) New added in v1.11.6 

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

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

func (*DriverSqlite) Open added in v1.11.6 

func (d *DriverSqlite) Open(config *ConfigNode) (*sql.DB, error)

Open creates and returns a underlying sql.DB object for sqlite.

func (*DriverSqlite) TableFields added in v1.11.6 

func (d *DriverSqlite) 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.

Also see DriverMysql.TableFields.

func (*DriverSqlite) Tables added in v1.11.6 

func (d *DriverSqlite) 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 Link interface {
	Query(sql string, args ...interface{}) (*sql.Rows, error)
	Exec(sql string, args ...interface{}) (sql.Result, error)
	Prepare(sql string) (*sql.Stmt, error)
	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)
	IsTransaction() bool
}

Link is a common database function wrapper interface.

type List 

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

type Logger added in v1.16.5 

type Logger interface {
	Error(ctx context.Context, s string)
	Debug(ctx context.Context, s string)
}

Logger is the logging interface for DB.

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) And 

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

And adds "AND" condition to the where statement. Deprecated, use Where instead.

func (*Model) Args added in v1.14.4 

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

Args sets custom arguments for model operation.

func (*Model) Array added in v1.11.6 

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 added in v1.11.2 

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

As sets an alias name for current table.

func (*Model) Avg added in v1.15.7 

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(duration time.Duration, name ...string) *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.

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`.

The optional parameter `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`.

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 added in v1.15.7 

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

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

func (*Model) Ctx added in v1.14.6 

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

Ctx sets the context for current operation.

func (*Model) DB added in v1.10.1 

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 added in v1.15.7 

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 added in v1.15.7 

func (m *Model) Distinct() *Model

Distinct forces the query to only return distinct results.

func (*Model) FieldAvg added in v1.16.6 

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 added in v1.16.6 

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 added in v1.16.6 

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 added in v1.16.6 

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 added in v1.16.6 

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.

func (*Model) FieldsEx added in v1.10.0 

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.

func (*Model) FieldsExStr added in v1.11.5 

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

FieldsExStr 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."). Deprecated, use GetFieldsExStr instead.

func (*Model) FieldsStr added in v1.11.5 

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

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

func (*Model) Filter 

func (m *Model) Filter() *Model

Filter marks filtering the fields which does not exist in the fields of the operated table. Note that this function supports only single table operations. Deprecated, filter feature is automatically enabled from GoFrame v1.16.0, it is so no longer used.

func (*Model) FindAll added in v1.10.1 

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

FindAll retrieves and returns Result by by Model.WherePri and Model.All. Also see Model.WherePri and Model.All.

func (*Model) FindArray added in v1.11.6 

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

FindArray 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. Also see Model.WherePri and Model.Value.

func (*Model) FindCount added in v1.10.1 

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

FindCount retrieves and returns the record number by Model.WherePri and Model.Count. Also see Model.WherePri and Model.Count.

func (*Model) FindOne added in v1.10.1 

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

FindOne retrieves and returns a single Record by Model.WherePri and Model.One. Also see Model.WherePri and Model.One.

func (*Model) FindScan added in v1.11.0 

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

FindScan retrieves and returns the record/records by Model.WherePri and Model.Scan. Also see Model.WherePri and Model.Scan.

func (*Model) FindValue added in v1.10.1 

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

FindValue retrieves and returns single field value by Model.WherePri and Model.Value. Also see Model.WherePri and Model.Value.

func (*Model) ForPage 

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

ForPage is alias of Model.Page. See Model.Page. Deprecated, use Page instead.

func (*Model) GetCtx added in v1.16.0 

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 added in v1.13.6 

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 added in v1.13.6 

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 added in v1.10.1 

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

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

func (*Model) GroupBy 

func (m *Model) GroupBy(groupBy string) *Model

GroupBy is alias of Model.Group. See Model.Group. Deprecated, use Group instead.

func (*Model) Handler added in v1.16.5 

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 added in v1.13.3 

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

HasField determine whether the field exists in the table.

func (*Model) Having added in v1.12.2 

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) Increment added in v1.15.7 

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, like: Table("user").InnerJoin("user_detail", "user_detail.uid=user.uid") Table("user", "u").InnerJoin("user_detail", "ud", "ud.uid=u.uid") Table("user", "u").InnerJoin("SELECT xxx FROM xxx AS a", "a.uid=u.uid")

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 added in v1.15.7 

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 added in v1.11.5 

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, like: Table("user").LeftJoin("user_detail", "user_detail.uid=user.uid") Table("user", "u").LeftJoin("user_detail", "ud", "ud.uid=u.uid") Table("user", "u").LeftJoin("SELECT xxx FROM xxx AS a", "a.uid=u.uid")

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 added in v1.11.7 

func (m *Model) LockShared() *Model

LockShared sets the lock in share mode for current operation.

func (*Model) LockUpdate added in v1.11.7 

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 added in v1.15.7 

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

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

func (*Model) Min added in v1.15.7 

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 added in v1.10.1 

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 added in v1.16.5 

func (m *Model) OmitEmptyData() *Model

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

func (*Model) OmitEmptyWhere added in v1.16.5 

func (m *Model) OmitEmptyWhere() *Model

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

func (*Model) OmitNil added in v1.16.6 

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 added in v1.16.6 

func (m *Model) OmitNilData() *Model

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

func (*Model) OmitNilWhere added in v1.16.6 

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 added in v1.16.3 

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 added in v1.16.3 

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

OnDuplicateEx sets the excluding columns for operations when columns conflicts 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) Option added in v1.9.7 

func (m *Model) Option(option int) *Model

Option adds extra operation option for the model. Deprecated, use separate operations instead.

func (*Model) Or 

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

Or adds "OR" condition to the where statement. Deprecated, use WhereOr instead.

func (*Model) Order added in v1.10.1 

func (m *Model) Order(orderBy ...string) *Model

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

func (*Model) OrderAsc added in v1.15.7 

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

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

func (*Model) OrderBy 

func (m *Model) OrderBy(orderBy string) *Model

OrderBy is alias of Model.Order. See Model.Order. Deprecated, use Order instead.

func (*Model) OrderDesc added in v1.15.7 

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

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

func (*Model) OrderRandom added in v1.15.7 

func (m *Model) OrderRandom() *Model

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

func (*Model) Page added in v1.10.1 

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) Raw added in v1.16.3 

func (m *Model) 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)

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, like: Table("user").RightJoin("user_detail", "user_detail.uid=user.uid") Table("user", "u").RightJoin("user_detail", "ud", "ud.uid=u.uid") Table("user", "u").RightJoin("SELECT xxx FROM xxx AS a", "a.uid=u.uid")

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 added in v1.13.2 

func (m *Model) ScanList(listPointer interface{}, attributeName string, relation ...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. Usage example: 

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

var users []*Entity or var users []Entity

ScanList(&users, "User") ScanList(&users, "UserDetail", "User", "uid:Uid") ScanList(&users, "UserScores", "User", "uid: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. 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 (*Model) Schema added in v1.11.1 

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

Schema sets the schema for current operation.

func (*Model) Select 

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

Select is alias of Model.All. See Model.All. Deprecated, use All instead.

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) Struct 

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

Struct retrieves one record from table and converts it into given struct. The parameter `pointer` should be type of *struct/**struct. If type **struct is given, it can create the struct internally during converting.

Deprecated, use Scan instead.

func (*Model) Structs 

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

Structs retrieves records from table and converts them into given struct slice. The parameter `pointer` should be type of *[]struct/*[]*struct. It can create and fill the struct slice internally during converting.

Deprecated, use Scan instead.

func (*Model) Sum added in v1.15.7 

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

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

func (*Model) TX added in v1.10.1 

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

TX sets/changes the transaction for current operation.

func (*Model) TableFields added in v1.15.6 

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 added in v1.16.0 

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 added in v1.16.3 

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 added in v1.16.3 

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 added in v1.12.2 

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) 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 added in v1.15.7 

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

WhereBetween builds `column BETWEEN min AND max` statement.

func (*Model) WhereGT added in v1.16.3 

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

WhereGT builds `column > value` statement.

func (*Model) WhereGTE added in v1.16.3 

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

WhereGTE builds `column >= value` statement.

func (*Model) WhereIn added in v1.15.7 

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

WhereIn builds `column IN (in)` statement.

func (*Model) WhereLT added in v1.16.3 

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

WhereLT builds `column < value` statement.

func (*Model) WhereLTE added in v1.16.3 

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

WhereLTE builds `column <= value` statement.

func (*Model) WhereLike added in v1.15.7 

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

WhereLike builds `column LIKE like` statement.

func (*Model) WhereNot added in v1.16.0 

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

WhereNot builds `column != value` statement.

func (*Model) WhereNotBetween added in v1.15.7 

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

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

func (*Model) WhereNotIn added in v1.15.7 

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

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

func (*Model) WhereNotLike added in v1.15.7 

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

WhereNotLike builds `column NOT LIKE like` statement.

func (*Model) WhereNotNull added in v1.15.7 

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

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

func (*Model) WhereNull added in v1.15.7 

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

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

func (*Model) WhereOr added in v1.15.7 

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

WhereOr adds "OR" condition to the where statement.

func (*Model) WhereOrBetween added in v1.15.7 

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

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

func (*Model) WhereOrGT added in v1.16.3 

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

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

func (*Model) WhereOrGTE added in v1.16.3 

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

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

func (*Model) WhereOrIn added in v1.15.7 

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

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

func (*Model) WhereOrLT added in v1.16.3 

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

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

func (*Model) WhereOrLTE added in v1.16.3 

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

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

func (*Model) WhereOrLike added in v1.15.7 

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

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

func (*Model) WhereOrNotBetween added in v1.15.7 

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 added in v1.15.7 

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

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

func (*Model) WhereOrNotLike added in v1.15.7 

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

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

func (*Model) WhereOrNotNull added in v1.15.7 

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 added in v1.15.7 

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

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

func (*Model) WhereOrf added in v1.16.3 

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

WhereOrf builds `OR` condition string using fmt.Sprintf and arguments.

func (*Model) WherePri added in v1.10.1 

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 added in v1.16.3 

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 place holder in `format`, the extra `args` will be used as the where condition arguments of the Model.

func (*Model) With added in v1.15.4 

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 added in v1.15.4 

func (m *Model) WithAll() *Model

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

type ModelHandler added in v1.16.5 

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 added in v1.16.5 

type ModelWhereHolder struct {
	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.
}

ModelWhereHolder is the holder for where condition preparing.

type Raw added in v1.14.6 

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 added in v1.9.7 

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

GMap converts `r` to a gmap.

func (Record) Interface added in v1.16.5 

func (r Record) Interface() interface{}

Interface converts and returns `r` as type of interface{}.

func (Record) IsEmpty added in v1.10.0 

func (r Record) IsEmpty() bool

IsEmpty checks and returns whether `r` is empty.

func (Record) Json added in v1.9.7 

func (r Record) Json() string

Json converts `r` to JSON format content.

func (Record) Map added in v1.9.7 

func (r Record) Map() Map

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

func (Record) Struct added in v1.9.7 

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 added in v1.9.7 

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 added in v1.11.6 

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 added in v1.12.2 

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

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

func (Result) Interface added in v1.16.5 

func (r Result) Interface() interface{}

Interface converts and returns `r` as type of interface{}.

func (Result) IsEmpty added in v1.10.0 

func (r Result) IsEmpty() bool

IsEmpty checks and returns whether `r` is empty.

func (Result) Json added in v1.9.7 

func (r Result) Json() string

Json converts `r` to JSON format content.

func (Result) Len added in v1.13.2 

func (r Result) Len() int

Len returns the length of result list.

func (Result) List added in v1.9.7 

func (r Result) List() List

List converts `r` to a List.

func (Result) MapKeyInt added in v1.9.7 

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 added in v1.9.7 

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 added in v1.9.7 

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 added in v1.13.2 

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 added in v1.9.7 

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 added in v1.9.7 

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 added in v1.9.7 

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 added in v1.13.2 

func (r Result) ScanList(listPointer interface{}, bindToAttrName string, relationKV ...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. Usage example: 

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

var users []*Entity or var users []Entity

ScanList(&users, "User") ScanList(&users, "UserDetail", "User", "uid:Uid") ScanList(&users, "UserScores", "User", "uid: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 added in v1.13.2 

func (r Result) Size() int

Size is alias of function Len.

func (Result) Structs added in v1.9.7 

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 added in v1.9.7 

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

Xml converts `r` to XML format content.

type Schema added in v1.11.2 

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

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

func (*Schema) Model added in v1.11.2 

func (s *Schema) Model(table string) *Model

Model is alias of Core.Table. See Core.Table.

func (*Schema) Table added in v1.11.2 

func (s *Schema) Table(table string) *Model

Table creates and returns a new ORM model. The parameter `tables` can be more than one table names, like : "user", "user u", "user, user_detail", "user u, user_detail ud"

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.
}

Sql is the sql recording struct.

type SqlResult added in v1.11.7 

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

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

func (*SqlResult) LastInsertId added in v1.11.7 

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 added in v1.11.7 

func (r *SqlResult) MustGetAffected() int64

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

func (*SqlResult) MustGetInsertId added in v1.11.7 

func (r *SqlResult) MustGetInsertId() int64

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

func (*SqlResult) RowsAffected added in v1.11.7 

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 added in v1.15.2 

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 added in v1.15.2 

func (s *Stmt) Close() error

Close closes the statement.

func (*Stmt) Exec added in v1.15.2 

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 added in v1.15.2 

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 added in v1.15.2 

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 added in v1.15.2 

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 added in v1.15.2 

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 added in v1.15.2 

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 added in v1.16.0 

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 added in v1.15.7 

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 added in v1.16.0 

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 queries 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 added in v1.16.0 

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 added in v1.11.5 

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 added in v1.16.4 

func (tx *TX) IsClosed() bool

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

func (*TX) Model added in v1.11.0 

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{}) (rows *sql.Rows, err error)

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

func (*TX) Raw added in v1.16.3 

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 added in v1.15.7 

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 added in v1.15.7 

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) Schema added in v1.11.2 

func (tx *TX) Schema(schema string) *Schema

Schema creates and returns a initialization model from schema, from which it can then create a Model.

func (*TX) Transaction added in v1.15.7 

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 added in v1.15.4 

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 a index).
	Default interface{} // Default value for the field.
	Extra   string      // Extra information.
	Comment string      // 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.