orm

package module
Version: v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Feb 19, 2021 License: Apache-2.0 Imports: 41 Imported by: 3

README

核心结构简介

与GoFrame/orm兼容,主要是修改了gf/database/gdb目录

GoFrame地址

github地址

  • DB interface是直接操作数据库的接口,里面定义了一系列操作数据库的方法。
type DB interface {
        Insert(table string, data interface{}, batch ...int) (sql.Result, error)
        InsertIgnore(table string, data interface{}, batch ...int) (sql.Result, error)
        Replace(table string, data interface{}, batch ...int) (sql.Result, error)
        Save(table string, data interface{}, batch ...int) (sql.Result, error)
        ...
} 
  • Core是数据库管理的基础结构。只实现了 DB接口的一部分方法,是所有SQL驱动的基类(父类)。

    各种数据库驱动要想操作数据,必须完全实现DB接口,但这必定会造成代码冗余。

    例如:

    Mysql驱动实现了 Insert()、InsertIgnore()、Replace()、Save()...

    Pgsql也实现了 Insert()、InsertIgnore()、Replace()、Save()...

    这部分公共的方法完全可以抽取出来,只让Core结构体实现,所有的数据库驱动只要继承(内嵌)Core结构体即可;

    这样各种数据库驱动就间接的实现了 Insert()、InsertIgnore()、Replace()、Save()...等放法。

type Core struct {
	DB     DB              // DB 接口对象。持有DB实例,使Model结构体具备操作数据库的能力。
    group  string          // 配置组的组名。
    debug  *gtype.Bool     // 为数据库启用debug模式,该模式可以在运行时更改。
    cache  *gcache.Cache   // 缓存管理器,仅缓存SQL结果。
    schema *gtype.String   // 当前对象对象的自定义架构,可以方便的在运行时切换数据库。
    logger *glog.Logger    // Logger.
    config *ConfigNode     // 当前配置节点
    ctx    context.Context // 仅链接操作的上下文。
}  
                 
  • Modelormdao (Data Access Object)数据库访问对象
type Model struct {
    db    DB       // 底层数据库接口。持有这个实例就具备了操作数据的能力。
    tx    *TX      // 底层事务管理接口。   
    ...
}

Documentation

Overview

Package gdb provides ORM features for popular relationship databases.

Example (Transaction)
db.Transaction(func(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"
)
View Source
const (
	OPTION_OMITEMPTY  = 1
	OPTION_ALLOWEMPTY = 2
)
View Source
const (
	DefaultGroupName = "default" // Default group name.
)

Variables

View Source
var (
	// ErrNoRows is alias of sql.ErrNoRows.
	ErrNoRows = sql.ErrNoRows
)

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

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 <obj> should be type of *map/map/*struct/struct. It supports inherit struct definition for struct.

func DataToMapDeep

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

DataToMapDeep converts <value> to map type recursively. The parameter <value> should be type of *map/map/*struct/struct. It supports inherit struct definition for struct.

func FormatSqlWithArgs

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

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

func GetDefaultGroup

func GetDefaultGroup() string

GetDefaultGroup returns the { name of default configuration.

func GetInsertOperationByOption

func GetInsertOperationByOption(option int) string

GetInsertOperationByOption returns proper insert option with given parameter <option>.

func GetPrimaryKey

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

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

func GetPrimaryKeyCondition

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

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

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

func 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

func IsConfigured() bool

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

func ListItemValues

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

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

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

func ListItemValuesUnique

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

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

func Register

func Register(name string, driver Driver) error

Register registers custom database driver to gdb.

func SetConfig

func SetConfig(config Config)

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

func SetConfigGroup

func SetConfigGroup(group string, nodes ConfigGroup)

SetConfigGroup sets the configuration for given group.

func SetDefaultGroup

func SetDefaultGroup(name string)

SetDefaultGroup sets the group name for default configuration.

Types

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.
	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.
	LinkInfo             string        `json:"link"`                 // (Optional) Custom link information, when it is used, configuration Host/Port/User/Pass/Name are ignored.
	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 connection TTL configuration for underlying connection pool.
	QueryTimeout         time.Duration `json:"queryTimeout"`         // (Optional) Max query time for per dql.
	ExecTimeout          time.Duration `json:"execTimeout"`          // (Optional) Max exec time for dml.
	TranTimeout          time.Duration `json:"tranTimeout"`          // (Optional) Max exec time time for a transaction.
	PrepareTimeout       time.Duration `json:"prepareTimeout"`       // (Optional) Max exec time time for prepare operation.
	CreatedAt            string        `json:"createdAt"`            // (Optional) The filed name of table for automatic-filled created datetime.
	UpdatedAt            string        `json:"updatedAt"`            // (Optional) The filed name of table for automatic-filled updated datetime.
	DeletedAt            string        `json:"deletedAt"`            // (Optional) The filed name of table for automatic-filled updated datetime.
	TimeMaintainDisabled bool          `json:"timeMaintainDisabled"` // (Optional) Disable the automatic time maintaining feature.
}

ConfigNode is configuration for one node.

func (*ConfigNode) String

func (node *ConfigNode) String() string

String returns the node as string.

type Core

type Core struct {
	DB DB // DB interface object.
	// contains filtered or unexported fields
}

Core is the base struct for database management.

func (*Core) Begin

func (c *Core) Begin() (*TX, 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) Ctx

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

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

func (*Core) Delete

func (c *Core) Delete(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) DoBatchInsert

func (c *Core) DoBatchInsert(link Link, table string, list interface{}, option int, batch ...int) (result sql.Result, err error)

DoBatchInsert batch inserts/replaces/saves data. This function is usually used for custom interface definition, you do not need call it manually.

func (*Core) DoDelete

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

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

func (*Core) DoExec

func (c *Core) DoExec(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

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

DoGetAll queries and returns data records from database.

func (*Core) DoInsert

func (c *Core) DoInsert(link Link, table string, data interface{}, option int, batch ...int) (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 (*Core) DoPrepare

func (c *Core) DoPrepare(link Link, sql string) (*Stmt, error)

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

func (*Core) DoQuery

func (c *Core) DoQuery(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

func (c *Core) DoUpdate(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

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

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

GetAll queries and returns data records from database.

func (*Core) GetArray

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

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

func (*Core) GetCache

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

GetCache returns the internal cache object.

func (*Core) GetChars

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

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

func (*Core) GetConfig

func (c *Core) GetConfig() *ConfigNode

GetConfig returns the current used node configuration.

func (*Core) GetCount

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

GetCount queries and returns the count from database.

func (*Core) GetCtx

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

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

func (*Core) GetCtxTimeout

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

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

func (*Core) GetDebug

func (c *Core) GetDebug() bool

GetDebug returns the debug value.

func (*Core) GetDryRun

func (c *Core) GetDryRun() bool

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

func (*Core) GetGroup

func (c *Core) GetGroup() string

GetGroup returns the group string configured.

func (*Core) GetLogger

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

GetLogger returns the logger of the orm.

func (*Core) GetMaster

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

GetMaster 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) GetOne

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

GetOne queries and returns one record from database.

func (*Core) GetPrefix

func (c *Core) GetPrefix() string

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

func (*Core) GetScan

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

func (c *Core) GetSchema() string

GetSchema returns the schema configured.

func (*Core) GetSlave

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

GetSlave 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) GetStruct

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

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

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

func (c *Core) HandleSqlBeforeCommit(sql string) string

HandleSqlBeforeCommit handles the sql before posts it to database. It does nothing in default.

func (*Core) HasTable

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

HasTable determine whether the table name exists in the database.

func (*Core) Insert

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

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

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

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

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

func (*Core) Master

func (c *Core) Master() (*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 (*Core) Model

func (c *Core) Model(table ...string) *Model

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

func (*Core) PingMaster

func (c *Core) PingMaster() error

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

func (*Core) PingSlave

func (c *Core) PingSlave() error

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

func (*Core) Prepare

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

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

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

func (*Core) Query

func (c *Core) Query(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

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

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

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

func (*Core) QuoteString

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

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

func (*Core) QuoteWord

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.

func (*Core) Replace

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

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

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

Schema creates and returns a schema.

func (*Core) SetDebug

func (c *Core) SetDebug(debug bool)

SetDebug enables/disables the debug mode.

func (*Core) SetDryRun

func (c *Core) SetDryRun(enabled bool)

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

func (*Core) SetLogger

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

SetLogger sets the logger for orm.

func (*Core) SetMaxConnLifetime

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

SetMaxConnLifetime sets the connection TTL for underlying connection pool. If parameter <d> <= 0, it means the connection never expires.

func (*Core) SetMaxIdleConnCount

func (c *Core) SetMaxIdleConnCount(n int)

SetMaxIdleConnCount sets the max idle connection count for underlying connection pool.

func (*Core) SetMaxOpenConnCount

func (c *Core) SetMaxOpenConnCount(n int)

SetMaxOpenConnCount sets the max open connection count for underlying connection pool.

func (*Core) SetSchema

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

func (c *Core) Slave() (*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 (*Core) Table

func (c *Core) Table(table ...string) *Model

Table 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. Table names:

Table("user")
Table("user u")
Table("user, user_detail")
Table("user u, user_detail ud")

2. Table name with alias: Table("user", "u")

func (*Core) TableFields

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

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

Note that it returns a map containing the field name and its corresponding fields. As a map is unsorted, the TableField struct has 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

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

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

It does nothing in default.

func (*Core) Transaction

func (c *Core) Transaction(f func(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) Update

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

type Counter

type Counter struct {
	Field string
	Value float64
}

Counter is the type for update count.

type DB

type DB interface {

	// ===========================================================================
	// 以下6个方法仅被databaseDriver(数据库驱动)实现。
	// ===========================================================================
	// Open creates a raw connection object for database with given node configuration.
	// Note that it is not recommended using the this function manually.
	Open(config *ConfigNode) (*sql.DB, error)
	Tables(schema ...string) (tables []string, err error)
	TableFields(table string, schema ...string) (map[string]*TableField, error)
	GetChars() (charLeft string, charRight string)
	FilteredLinkInfo() string

	// HandleSqlBeforeCommit 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.
	HandleSqlBeforeCommit(link Link, sql string, args []interface{}) (string, []interface{})

	// ===========================================================================
	// Model creation.模型操作,以下所有方法都是公共方法,只被各种数据库驱动实现。
	// ===========================================================================
	Table(table ...string) *Model
	Model(table ...string) *Model
	Schema(schema string) *Schema

	// 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.
	Ctx(ctx context.Context) DB

	Query(sql string, args ...interface{}) (*sql.Rows, error)
	Exec(sql string, args ...interface{}) (sql.Result, error)
	Prepare(sql string, execOnMaster ...bool) (*Stmt, error)

	Insert(table string, data interface{}, batch ...int) (sql.Result, error)
	InsertIgnore(table string, data interface{}, batch ...int) (sql.Result, error)
	Replace(table string, data interface{}, batch ...int) (sql.Result, error)
	Save(table string, data interface{}, batch ...int) (sql.Result, error)

	Update(table string, data interface{}, condition interface{}, args ...interface{}) (sql.Result, error)
	Delete(table string, condition interface{}, args ...interface{}) (sql.Result, error)

	DoQuery(link Link, sql string, args ...interface{}) (rows *sql.Rows, err error)
	DoGetAll(link Link, sql string, args ...interface{}) (result Result, err error)
	DoExec(link Link, sql string, args ...interface{}) (result sql.Result, err error)
	DoPrepare(link Link, sql string) (*Stmt, error)
	DoInsert(link Link, table string, data interface{}, option int, batch ...int) (result sql.Result, err error)
	DoBatchInsert(link Link, table string, list interface{}, option int, batch ...int) (result sql.Result, err error)
	DoUpdate(link Link, table string, data interface{}, condition string, args ...interface{}) (result sql.Result, err error)
	DoDelete(link Link, table string, condition string, args ...interface{}) (result sql.Result, err error)

	GetAll(sql string, args ...interface{}) (Result, error)
	GetOne(sql string, args ...interface{}) (Record, error)
	GetValue(sql string, args ...interface{}) (Value, error)
	GetArray(sql string, args ...interface{}) ([]Value, error)
	GetCount(sql string, args ...interface{}) (int, error)
	GetStruct(objPointer interface{}, sql string, args ...interface{}) error
	GetStructs(objPointerSlice interface{}, sql string, args ...interface{}) error
	GetScan(objPointer interface{}, sql string, args ...interface{}) error

	Master() (*sql.DB, error)
	Slave() (*sql.DB, error)

	PingMaster() error
	PingSlave() error

	Begin() (*TX, error)
	Transaction(f func(tx *TX) error) (err error)

	GetCache() *gcache.Cache
	SetDebug(debug bool)
	GetDebug() bool
	SetSchema(schema string)
	GetSchema() string
	GetPrefix() string
	GetGroup() string
	SetDryRun(dryrun bool)
	GetDryRun() bool
	SetLogger(logger *glog.Logger)
	GetLogger() *glog.Logger
	GetConfig() *ConfigNode
	SetMaxIdleConnCount(n int)
	SetMaxOpenConnCount(n int)
	SetMaxConnLifetime(d time.Duration)

	GetCtx() context.Context
	GetMaster(schema ...string) (*sql.DB, error)
	GetSlave(schema ...string) (*sql.DB, error)
	QuoteWord(s string) string
	QuoteString(s string) string
	QuotePrefixTableName(table string) string
	HasTable(name string) (bool, error)
	// contains filtered or unexported methods
}

DB defines the interfaces for ORM operations. 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. 定义ORM操作的接口。

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 Driver

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

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

type DriverMssql

type DriverMssql struct {
	*Core
}

DriverMssql is the driver for SQL server database.

func (*DriverMssql) FilteredLinkInfo

func (d *DriverMssql) FilteredLinkInfo() string

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

func (*DriverMssql) GetChars

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

GetChars returns the security char for this type of database.

func (*DriverMssql) HandleSqlBeforeCommit

func (d *DriverMssql) HandleSqlBeforeCommit(link Link, sql string, args []interface{}) (string, []interface{})

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

func (*DriverMssql) New

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

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

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

func (*DriverMssql) TableFields

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

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

func (*DriverMssql) Tables

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

type DriverMysql

type DriverMysql struct {
	*Core
}

DriverMysql is the driver for mysql database.

func (*DriverMysql) FilteredLinkInfo

func (d *DriverMysql) FilteredLinkInfo() string

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

func (*DriverMysql) GetChars

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

GetChars returns the security char for this type of database.

func (*DriverMysql) HandleSqlBeforeCommit

func (d *DriverMysql) HandleSqlBeforeCommit(link Link, sql string, args []interface{}) (string, []interface{})

HandleSqlBeforeCommit handles the sql before posts it to database.

func (*DriverMysql) New

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

New creates and returns a database object for mysql. It implements the interface of gdb.Driver for extra database driver installation. 创建并返回mysql的数据库对象。它实现了gdb.Driver的接口,用于额外的数据库驱动程序安装。

func (*DriverMysql) Open

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

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

func (*DriverMysql) TableFields

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

func (*DriverMysql) Tables

func (d *DriverMysql) 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. 检索并返回当前模式的表。它主要用于cli工具链中,用于自动生成模型。

type DriverOracle

type DriverOracle struct {
	*Core
}

DriverOracle is the driver for oracle database.

func (*DriverOracle) DoBatchInsert

func (d *DriverOracle) DoBatchInsert(link Link, table string, list interface{}, option int, batch ...int) (result sql.Result, err error)

func (*DriverOracle) DoInsert

func (d *DriverOracle) DoInsert(link Link, table string, data interface{}, option int, batch ...int) (result sql.Result, err error)

func (*DriverOracle) FilteredLinkInfo

func (d *DriverOracle) FilteredLinkInfo() string

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

func (*DriverOracle) GetChars

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

GetChars returns the security char for this type of database.

func (*DriverOracle) HandleSqlBeforeCommit

func (d *DriverOracle) HandleSqlBeforeCommit(link Link, sql string, args []interface{}) (newSql string, newArgs []interface{})

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

func (*DriverOracle) New

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

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

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

func (*DriverOracle) TableFields

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

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

func (*DriverOracle) Tables

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

type DriverPgsql

type DriverPgsql struct {
	*Core
}

DriverPgsql is the driver for postgresql database.

func (*DriverPgsql) FilteredLinkInfo

func (d *DriverPgsql) FilteredLinkInfo() string

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

func (*DriverPgsql) GetChars

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

GetChars returns the security char for this type of database.

func (*DriverPgsql) HandleSqlBeforeCommit

func (d *DriverPgsql) HandleSqlBeforeCommit(link Link, sql string, args []interface{}) (string, []interface{})

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

func (*DriverPgsql) New

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

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

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

func (*DriverPgsql) TableFields

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

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

func (*DriverPgsql) Tables

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

type DriverSqlite

type DriverSqlite struct {
	*Core
}

DriverSqlite is the driver for sqlite database.

func (*DriverSqlite) FilteredLinkInfo

func (d *DriverSqlite) FilteredLinkInfo() string

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

func (*DriverSqlite) GetChars

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

GetChars returns the security char for this type of database.

func (*DriverSqlite) HandleSqlBeforeCommit

func (d *DriverSqlite) HandleSqlBeforeCommit(link Link, sql string, args []interface{}) (string, []interface{})

HandleSqlBeforeCommit deals with the sql string before commits it to underlying sql driver. TODO 需要增加对Save方法的支持,可使用正则来实现替换, TODO 将ON DUPLICATE KEY UPDATE触发器修改为两条SQL语句(INSERT OR IGNORE & UPDATE)

func (*DriverSqlite) New

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

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

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

func (*DriverSqlite) TableFields

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

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

func (*DriverSqlite) Tables

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

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

Link is a common database function wrapper interface.

type List

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

type Map

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

type Model

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

Model is the DAO for ORM.

func (*Model) And

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

And adds "AND" condition to the where statement.

func (*Model) Args

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

Args sets custom arguments for model operation.

func (*Model) As

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

As sets an alias name for current table.

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(limit int, callback func(result Result, err error) bool)

Chunk iterates the query result with given size and callback 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 (原FindCount) retrieves and returns the record number by Model.WherePri and Model.Count. Also see Model.WherePri and Model.Count.

func (*Model) Ctx

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

Ctx sets the context for current operation.

func (*Model) DB

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

DB sets/changes the db object for current operation.

func (*Model) Data

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

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

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

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

Array (原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) FieldValue

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

FieldValue (原FindValue) retrieves and returns single field value by Model.WherePri and Model.Value. Also see Model.WherePri and Model.Value.

func (*Model) Fields

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

Fields 指定需要操作的表字段,包括查询字段、写入字段、更新字段等, 多个字段之间用','连接。 The parameter <fieldNamesOrMapStruct> can be type of string/map/*map/struct/*struct.

func (*Model) FieldsEx

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

FieldsEx sets 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) FieldsExName

func (m *Model) FieldsExName(excludeFields string, prefix ...string) string

FieldsExName (原FieldsExStr) 检索并返回表中例外的字段的名称。

参数<excludeFields>是被排除,不被检索的字段。各个字段之间用','连接。 可选参数 <prefix> 为每个字段指定前缀, eg: FieldsExStr("id", "u.").

func (*Model) FieldsName

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

FieldsName (原: FieldsStr)检索并返回表中所有的字段名,各字段之间用','连接。 可选参数 <prefix> 为每个字段指定前缀, eg: FieldsStr("u.").

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.

func (*Model) Find

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

Find (原FindAll) retrieves and returns Result by by Model.WherePri and Model.All. Also see Model.WherePri and Model.All.

func (*Model) Group

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

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

func (*Model) HasField

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

HasField determine whether the field exists in the table.

func (*Model) Having

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

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

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

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

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

func (*Model) LeftJoin

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

LeftJoin does "LEFT JOIN ... ON ..." statement on the model. The parameter <table> can be joined table and its joined condition, and also with its alias name, 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

func (m *Model) LockShared() *Model

LockShared 在当前操作上为 Model 设置"共享锁"。

共享锁可以避免被选择的行被修改直到事务提交。

func (*Model) LockUpdate

func (m *Model) LockUpdate() *Model

LockUpdate 在当前操作上为 Model 设置"FOR UPDATE"锁。

避免选择行被其它共享锁修改或删除。

func (*Model) Master

func (m *Model) Master() *Model

Master marks the following operation on master node.

func (*Model) Offset

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

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

func (*Model) OmitEmpty

func (m *Model) OmitEmpty() *Model

OmitEmpty sets OPTION_OMITEMPTY option for the model, which automatically filers the data and where attributes for empty values.

func (*Model) Option

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

Option adds extra operation option for the model.

func (*Model) Or

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

Or adds "OR" condition to the where statement.

func (*Model) Order

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

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

func (*Model) Page

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

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

func (*Model) 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 (原FindScan) automatically calls Struct or Structs function according to the type of parameter <pointer>. It calls function Struct if <pointer> is type of *struct/**struct. It calls function Structs if <pointer> is type of *[]struct/*[]*struct.

The optional parameter <where> is the same as the parameter of Model.WherePri function, see Model.WherePri and Model.scan.

Note that it returns sql.ErrNoRows if there's no record retrieved with the given conditions from table.

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

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

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

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

func (*Model) ScanList

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

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

Schema sets the schema for current operation.

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

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

TX sets/changes the transaction for current operation.

func (*Model) Take

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

Take (原FindOne) retrieves and returns a single Record by Model.WherePri and Model.One. Also see Model.WherePri and Model.One.

func (*Model) Unscoped

func (m *Model) Unscoped() *Model

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

func (*Model) Update

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

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

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

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

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

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

type Raw

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

type Record

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

func (Record) GMap

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

GMap converts <r> to a gmap.

func (Record) IsEmpty

func (r Record) IsEmpty() bool

IsEmpty checks and returns whether <r> is empty.

func (Record) Json

func (r Record) Json() string

Json converts <r> to JSON format content.

func (Record) Map

func (r Record) Map() Map

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

func (Record) Struct

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

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

Note that it returns sql.ErrNoRows if <r> is empty.

func (Record) ToJson

func (r Record) ToJson() string

Deprecated.

func (Record) ToMap

func (r Record) ToMap() Map

Deprecated.

func (Record) ToStruct

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

Deprecated.

func (Record) ToXml

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

Deprecated.

func (Record) Xml

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

Xml converts <r> to XML format content.

type Result

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

func (Result) Array

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

Array retrieves and returns specified column values as slice. The parameter <field> is optional is the column field is only one.

func (Result) Chunk

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

func (r Result) IsEmpty() bool

IsEmpty checks and returns whether <r> is empty.

func (Result) Json

func (r Result) Json() string

Json converts <r> to JSON format content.

func (Result) Len

func (r Result) Len() int

Len returns the length of result list.

func (Result) List

func (r Result) List() List

List converts <r> to a List.

func (Result) MapKeyInt

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

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

func (Result) MapKeyStr

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

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

func (Result) MapKeyUint

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

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

func (Result) MapKeyValue

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

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

func (Result) RecordKeyInt

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

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

func (Result) RecordKeyStr

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

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

func (Result) RecordKeyUint

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

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

func (Result) ScanList

func (r Result) ScanList(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

func (r Result) Size() int

Size is alias of function Len.

func (Result) Structs

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

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

func (Result) ToIntMap

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

Deprecated.

func (Result) ToIntRecord

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

Deprecated.

func (Result) ToJson

func (r Result) ToJson() string

Deprecated.

func (Result) ToList

func (r Result) ToList() List

Deprecated.

func (Result) ToStringMap

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

Deprecated.

func (Result) ToStringRecord

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

Deprecated.

func (Result) ToStructs

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

Deprecated.

func (Result) ToUintMap

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

Deprecated.

func (Result) ToUintRecord

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

Deprecated.

func (Result) ToXml

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

Deprecated.

func (Result) Xml

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

Xml converts <r> to XML format content.

type Schema

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

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

func (*Schema) Model

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

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

func (*Schema) Table

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

Sql is the sql recording struct.

type SqlResult

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

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

see sql.Result.LastInsertId

func (*SqlResult) MustGetAffected

func (r *SqlResult) MustGetAffected() int64

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

func (*SqlResult) MustGetInsertId

func (r *SqlResult) MustGetInsertId() int64

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

func (*SqlResult) RowsAffected

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

see sql.Result.RowsAffected

type Stmt

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

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

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

func (*Stmt) Close

func (s *Stmt) Close() error

Close closes the statement.

func (*Stmt) Exec

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

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

func (*Stmt) ExecContext

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

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

func (*Stmt) Query

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

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

func (*Stmt) QueryContext

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

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

func (*Stmt) QueryRow

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

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

Example usage:

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

func (*Stmt) QueryRowContext

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

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

type TX

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

TX is the struct for transaction management.

func (*TX) BatchInsert

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

BatchInsert batch inserts data. The parameter <list> must be type of slice of map or struct.

func (*TX) BatchInsertIgnore

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

BatchInsert batch inserts data with ignore option. The parameter <list> must be type of slice of map or struct.

func (*TX) BatchReplace

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

BatchReplace batch replaces data. The parameter <list> must be type of slice of map or struct.

func (*TX) BatchSave

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

BatchSave batch replaces data. The parameter <list> must be type of slice of map or struct.

func (*TX) Commit

func (tx *TX) Commit() error

Commit commits the 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(objPointer 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) InsertIgnore

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

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

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

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

func (*TX) Model

func (tx *TX) Model(table ...string) *Model

Model is alias of tx.Table. See tx.Table.

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) 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 the transaction.

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

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

func (tx *TX) Table(table ...string) *Model

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

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

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.

Directories

Path Synopsis
g

Jump to

Keyboard shortcuts

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