💎一站式轻松地调用各大LLM模型接口,支持GPT4、智谱、星火、月之暗面及文生图 广告
# package sql `import "database/sql"` sql包提供了保证SQL或类SQL数据库的泛用接口。 使用sql包时必须注入(至少)一个数据库驱动。参见[http://golang.org/s/sqldrivers](http://golang.org/s/sqldrivers) 获取驱动列表。 更多用法示例,参见wiki页面:[http://golang.org/s/sqlwiki](http://golang.org/s/sqlwiki)。 ## Index * [Variables](#pkg-variables) * [type Scanner](#Scanner) * [type NullBool](#NullBool) * [func (n \*NullBool) Scan(value interface{}) error](#NullBool.Scan) * [func (n NullBool) Value() (driver.Value, error)](#NullBool.Value) * [type NullInt64](#NullInt64) * [func (n \*NullInt64) Scan(value interface{}) error](#NullInt64.Scan) * [func (n NullInt64) Value() (driver.Value, error)](#NullInt64.Value) * [type NullFloat64](#NullFloat64) * [func (n \*NullFloat64) Scan(value interface{}) error](#NullFloat64.Scan) * [func (n NullFloat64) Value() (driver.Value, error)](#NullFloat64.Value) * [type NullString](#NullString) * [func (ns \*NullString) Scan(value interface{}) error](#NullString.Scan) * [func (ns NullString) Value() (driver.Value, error)](#NullString.Value) * [type RawBytes](#RawBytes) * [type Result](#Result) * [type DB](#DB) * [func Open(driverName, dataSourceName string) (\*DB, error)](#Open) * [func (db \*DB) Driver() driver.Driver](#DB.Driver) * [func (db \*DB) Ping() error](#DB.Ping) * [func (db \*DB) Close() error](#DB.Close) * [func (db \*DB) SetMaxOpenConns(n int)](#DB.SetMaxOpenConns) * [func (db \*DB) SetMaxIdleConns(n int)](#DB.SetMaxIdleConns) * [func (db \*DB) Exec(query string, args ...interface{}) (Result, error)](#DB.Exec) * [func (db \*DB) Query(query string, args ...interface{}) (\*Rows, error)](#DB.Query) * [func (db \*DB) QueryRow(query string, args ...interface{}) \*Row](#DB.QueryRow) * [func (db \*DB) Prepare(query string) (\*Stmt, error)](#DB.Prepare) * [func (db \*DB) Begin() (\*Tx, error)](#DB.Begin) * [type Row](#Row) * [func (r \*Row) Scan(dest ...interface{}) error](#Row.Scan) * [type Rows](#Rows) * [func (rs \*Rows) Columns() ([]string, error)](#Rows.Columns) * [func (rs \*Rows) Scan(dest ...interface{}) error](#Rows.Scan) * [func (rs \*Rows) Next() bool](#Rows.Next) * [func (rs \*Rows) Close() error](#Rows.Close) * [func (rs \*Rows) Err() error](#Rows.Err) * [type Stmt](#Stmt) * [func (s \*Stmt) Exec(args ...interface{}) (Result, error)](#Stmt.Exec) * [func (s \*Stmt) Query(args ...interface{}) (\*Rows, error)](#Stmt.Query) * [func (s \*Stmt) QueryRow(args ...interface{}) \*Row](#Stmt.QueryRow) * [func (s \*Stmt) Close() error](#Stmt.Close) * [type Tx](#Tx) * [func (tx \*Tx) Exec(query string, args ...interface{}) (Result, error)](#Tx.Exec) * [func (tx \*Tx) Query(query string, args ...interface{}) (\*Rows, error)](#Tx.Query) * [func (tx \*Tx) QueryRow(query string, args ...interface{}) \*Row](#Tx.QueryRow) * [func (tx \*Tx) Prepare(query string) (\*Stmt, error)](#Tx.Prepare) * [func (tx \*Tx) Stmt(stmt \*Stmt) \*Stmt](#Tx.Stmt) * [func (tx \*Tx) Commit() error](#Tx.Commit) * [func (tx \*Tx) Rollback() error](#Tx.Rollback) * [func Register(name string, driver driver.Driver)](#Register) ### Examples * [DB.Query](#example-DB-Query) * [DB.QueryRow](#example-DB-QueryRow) ## Variables ``` var ErrNoRows = errors.New("sql: no rows in result set") ``` 当QueryRow方法没有返回一个row时,调用返回值的Scan方法会返回ErrNoRows。此时,QueryRow返回一个占位的\*Row值,延迟本错误直到调用Scan方法时才释放。 ``` var ErrTxDone = errors.New("sql: Transaction has already been committed or rolled back") ``` ## func [Register](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L30 "View Source") ``` func Register(name string, driver driver.Driver) ``` Register注册并命名一个数据库,可以在Open函数中使用该命名启用该驱动。如果 Register注册同一名称两次,或者driver参数为nil,会导致panic。 ## type [Scanner](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L160 "View Source") ``` type Scanner interface { // Scan方法从数据库驱动获取一个值。 // // 参数src的类型保证为如下类型之一: // // int64 // float64 // bool // []byte // string // time.Time // nil - 表示NULL值 // // 如果不能不丢失信息的保存一个值,应返回错误。 Scan(src interface{}) error } ``` Scanner接口会被Rows或Row的Scan方法使用。 ## type [NullBool](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L136 "View Source") ``` type NullBool struct { Bool bool Valid bool // 如果Bool不是NULL则Valid为真 } ``` NullBool代表一个可为NULL的布尔值。NullBool实现了Scanner接口,因此可以作为Rows/Row的Scan方法的参数保存扫描结果,类似NullString。 ### func (\*NullBool) [Scan](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L142 "View Source") ``` func (n *NullBool) Scan(value interface{}) error ``` Scan实现了Scanner接口。 ### func (NullBool) [Value](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L152 "View Source") ``` func (n NullBool) Value() (driver.Value, error) ``` Value实现了driver.Valuer接口。 ## type [NullInt64](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L84 "View Source") ``` type NullInt64 struct { Int64 int64 Valid bool // 如果Int64不是NULL则Valid为真 } ``` NullInt64代表一个可为NULL的int64值。NullInt64实现了Scanner接口,因此可以作为Rows/Row的Scan方法的参数保存扫描结果,类似NullString。 ### func (\*NullInt64) [Scan](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L90 "View Source") ``` func (n *NullInt64) Scan(value interface{}) error ``` Scan实现了Scanner接口。 ### func (NullInt64) [Value](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L100 "View Source") ``` func (n NullInt64) Value() (driver.Value, error) ``` Value实现了driver.Valuer接口。 ## type [NullFloat64](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L110 "View Source") ``` type NullFloat64 struct { Float64 float64 Valid bool // 如果Float64不是NULL则Valid为真 } ``` NullFloat64代表一个可为NULL的float64值。NullFloat64实现了Scanner接口,因此可以作为Rows/Row的Scan方法的参数保存扫描结果,类似NullString。 ### func (\*NullFloat64) [Scan](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L116 "View Source") ``` func (n *NullFloat64) Scan(value interface{}) error ``` Scan实现了Scanner接口。 ### func (NullFloat64) [Value](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L126 "View Source") ``` func (n NullFloat64) Value() (driver.Value, error) ``` Value实现了driver.Valuer接口。 ## type [NullString](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L58 "View Source") ``` type NullString struct { String string Valid bool // 如果String不是NULL则Valid为真 } ``` NullString代表一个可为NULL的字符串。NullString实现了Scanner接口,因此可以作为Rows/Row的Scan方法的参数保存扫描结果: ``` var s NullString err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s) ... if s.Valid { // use s.String } else { // NULL value } ``` ### func (\*NullString) [Scan](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L64 "View Source") ``` func (ns *NullString) Scan(value interface{}) error ``` Scan实现了Scanner接口。 ### func (NullString) [Value](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L74 "View Source") ``` func (ns NullString) Value() (driver.Value, error) ``` Value实现了driver.Valuer接口。 ## type [RawBytes](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L43 "View Source") ``` type RawBytes []byte ``` RawBytes是一个字节切片,保管对内存的引用,为数据库自身所使用。在Scaner接口的Scan方法写入RawBytes数据后,该切片只在限次调用Next、Scan或Close方法之前合法。 ## type [Result](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1679 "View Source") ``` type Result interface { // LastInsertId返回一个数据库生成的回应命令的整数。 // 当插入新行时,一般来自一个"自增"列。 // 不是所有的数据库都支持该功能,该状态的语法也各有不同。 LastInsertId() (int64, error) // RowsAffected返回被update、insert或delete命令影响的行数。 // 不是所有的数据库都支持该功能。 RowsAffected() (int64, error) } ``` Result是对已执行的SQL命令的总结。 ## type [DB](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L196 "View Source") ``` type DB struct { // 内含隐藏或非导出字段 } ``` DB是一个数据库(操作)句柄,代表一个具有零到多个底层连接的连接池。它可以安全的被多个go程同时使用。 sql包会自动创建和释放连接;它也会维护一个闲置连接的连接池。如果数据库具有单连接状态的概念,该状态只有在事务中被观察时才可信。一旦调用了BD.Begin,返回的Tx会绑定到单个连接。当调用事务Tx的Commit或Rollback后,该事务使用的连接会归还到DB的闲置连接池中。连接池的大小可以用SetMaxIdleConns方法控制。 ### func [Open](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L429 "View Source") ``` func Open(driverName, dataSourceName string) (*DB, error) ``` Open打开一个dirverName指定的数据库,dataSourceName指定数据源,一般包至少括数据库文件名和(可能的)连接信息。 大多数用户会通过数据库特定的连接帮助函数打开数据库,返回一个\*DB。Go标准库中没有数据库驱动。参见[http://golang.org/s/sqldrivers](http://golang.org/s/sqldrivers)获取第三方驱动。 Open函数可能只是验证其参数,而不创建与数据库的连接。如果要检查数据源的名称是否合法,应调用返回值的Ping方法。 返回的DB可以安全的被多个go程同时使用,并会维护自身的闲置连接池。这样一来,Open函数只需调用一次。很少需要关闭DB。 ### func (\*DB) [Driver](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1031 "View Source") ``` func (db *DB) Driver() driver.Driver ``` Driver方法返回数据库下层驱动。 ### func (\*DB) [Ping](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L448 "View Source") ``` func (db *DB) Ping() error ``` Ping检查与数据库的连接是否仍有效,如果需要会创建连接。 ### func (\*DB) [Close](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L464 "View Source") ``` func (db *DB) Close() error ``` Close关闭数据库,释放任何打开的资源。一般不会关闭DB,因为DB句柄通常被多个go程共享,并长期活跃。 ### func (\*DB) [SetMaxOpenConns](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L550 "View Source") ``` func (db *DB) SetMaxOpenConns(n int) ``` SetMaxOpenConns设置与数据库建立连接的最大数目。 如果n大于0且小于最大闲置连接数,会将最大闲置连接数减小到匹配最大开启连接数的限制。 如果n <= 0,不会限制最大开启连接数,默认为0(无限制)。 ### func (\*DB) [SetMaxIdleConns](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L517 "View Source") ``` func (db *DB) SetMaxIdleConns(n int) ``` SetMaxIdleConns设置连接池中的最大闲置连接数。 如果n大于最大开启连接数,则新的最大闲置连接数会减小到匹配最大开启连接数的限制。 如果n <= 0,不会保留闲置连接。 ### func (\*DB) [Exec](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L862 "View Source") ``` func (db *DB) Exec(query string, args ...interface{}) (Result, error) ``` Exec执行一次命令(包括查询、删除、更新、插入等),不返回任何执行结果。参数args表示query中的占位参数。 ### func (\*DB) [Query](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L911 "View Source") ``` func (db *DB) Query(query string, args ...interface{}) (*Rows, error) ``` Query执行一次查询,返回多行结果(即Rows),一般用于执行select命令。参数args表示query中的占位参数。 Example ``` age := 27 rows, err := db.Query("SELECT name FROM users WHERE age=?", age) if err != nil { log.Fatal(err) } defer rows.Close() for rows.Next() { var name string if err := rows.Scan(&name); err != nil { log.Fatal(err) } fmt.Printf("%s is %d\n", name, age) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ### func (\*DB) [QueryRow](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L992 "View Source") ``` func (db *DB) QueryRow(query string, args ...interface{}) *Row ``` QueryRow执行一次查询,并期望返回最多一行结果(即Row)。QueryRow总是返回非nil的值,直到返回值的Scan方法被调用时,才会返回被延迟的错误。(如:未找到结果) Example ``` id := 123 var username string err := db.QueryRow("SELECT username FROM users WHERE id=?", id).Scan(&username) switch { case err == sql.ErrNoRows: log.Printf("No user with that ID.") case err != nil: log.Fatal(err) default: fmt.Printf("Username is %s\n", username) } ``` ### func (\*DB) [Prepare](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L820 "View Source") ``` func (db *DB) Prepare(query string) (*Stmt, error) ``` Prepare创建一个准备好的状态用于之后的查询和命令。返回值可以同时执行多个查询和命令。 ### func (\*DB) [Begin](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L999 "View Source") ``` func (db *DB) Begin() (*Tx, error) ``` Begin开始一个事务。隔离水平由数据库驱动决定。 ## type [Row](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1625 "View Source") ``` type Row struct { // 内含隐藏或非导出字段 } ``` QueryRow方法返回Row,代表单行查询结果。 ### func (\*Row) [Scan](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1635 "View Source") ``` func (r *Row) Scan(dest ...interface{}) error ``` Scan将该行查询结果各列分别保存进dest参数指定的值中。如果该查询匹配多行,Scan会使用第一行结果并丢弃其余各行。如果没有匹配查询的行,Scan会返回ErrNoRows。 ## type [Rows](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1518 "View Source") ``` type Rows struct { // 内含隐藏或非导出字段 } ``` Rows是查询的结果。它的游标指向结果集的第零行,使用Next方法来遍历各行结果: ``` rows, err := db.Query("SELECT ...") ... defer rows.Close() for rows.Next() { var id int var name string err = rows.Scan(&id, &name) ... } err = rows.Err() // get any error encountered during iteration ... ``` ### func (\*Rows) [Columns](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1562 "View Source") ``` func (rs *Rows) Columns() ([]string, error) ``` Columns返回列名。如果Rows已经关闭会返回错误。 ### func (\*Rows) [Scan](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1584 "View Source") ``` func (rs *Rows) Scan(dest ...interface{}) error ``` Scan将当前行各列结果填充进dest指定的各个值中。 如果某个参数的类型为*[]byte,Scan会保存对应数据的拷贝,该拷贝为调用者所有,可以安全的,修改或无限期的保存。如果参数类型为\*RawBytes可以避免拷贝;参见RawBytes的文档获取其使用的约束。 如果某个参数的类型为\*interface{},Scan会不做转换的拷贝底层驱动提供的值。如果值的类型为[]byte,会进行数据的拷贝,调用者可以安全使用该值。 ### func (\*Rows) [Next](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1535 "View Source") ``` func (rs *Rows) Next() bool ``` Next准备用于Scan方法的下一行结果。如果成功会返回真,如果没有下一行或者出现错误会返回假。Err应该被调用以区分这两种情况。 每一次调用Scan方法,甚至包括第一次调用该方法,都必须在前面先调用Next方法。 ### func (\*Rows) [Close](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1608 "View Source") ``` func (rs *Rows) Close() error ``` Close关闭Rows,阻止对其更多的列举。 如果Next方法返回假,Rows会自动关闭,满足。检查Err方法结果的条件。Close方法时幂等的(多次调用无效的成功),不影响Err方法的结果。 ### func (\*Rows) [Err](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1552 "View Source") ``` func (rs *Rows) Err() error ``` Err返回可能的、在迭代时出现的错误。Err需在显式或隐式调用Close方法后调用。 ## type [Stmt](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1237 "View Source") ``` type Stmt struct { // 内含隐藏或非导出字段 } ``` Stmt是准备好的状态。Stmt可以安全的被多个go程同时使用。 ### func (\*Stmt) [Exec](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1261 "View Source") ``` func (s *Stmt) Exec(args ...interface{}) (Result, error) ``` Exec使用提供的参数执行准备好的命令状态,返回Result类型的该状态执行结果的总结。 ### func (\*Stmt) [Query](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1382 "View Source") ``` func (s *Stmt) Query(args ...interface{}) (*Rows, error) ``` Query使用提供的参数执行准备好的查询状态,返回Rows类型查询结果。 ### func (\*Stmt) [QueryRow](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1458 "View Source") ``` func (s *Stmt) QueryRow(args ...interface{}) *Row ``` QueryRow使用提供的参数执行准备好的查询状态。如果在执行时遇到了错误,该错误会被延迟,直到返回值的Scan方法被调用时才释放。返回值总是非nil的。如果没有查询到结果,\*Row类型返回值的Scan方法会返回ErrNoRows;否则,Scan方法会扫描结果第一行并丢弃其余行。 示例用法: ``` var name string err := nameByUseridStmt.QueryRow(id).Scan(&name) ``` ### func (\*Stmt) [Close](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1467 "View Source") ``` func (s *Stmt) Close() error ``` Close关闭状态。 ## type [Tx](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1041 "View Source") ``` type Tx struct { // 内含隐藏或非导出字段 } ``` Tx代表一个进行中的数据库事务。 一次事务必须以对Commit或Rollback的调用结束。 调用Commit或Rollback后,所有对事务的操作都会失败并返回错误值ErrTxDone。 ### func (\*Tx) [Exec](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1179 "View Source") ``` func (tx *Tx) Exec(query string, args ...interface{}) (Result, error) ``` Exec执行命令,但不返回结果。例如执行insert和update。 ### func (\*Tx) [Query](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1213 "View Source") ``` func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error) ``` Query执行查询并返回零到多行结果(Rows),一般执行select命令。 ### func (\*Tx) [QueryRow](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1225 "View Source") ``` func (tx *Tx) QueryRow(query string, args ...interface{}) *Row ``` QueryRow执行查询并期望返回最多一行结果(Row)。QueryRow总是返回非nil的结果,查询失败的错误会延迟到在调用该结果的Scan方法时释放。 ### func (\*Tx) [Prepare](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1102 "View Source") ``` func (tx *Tx) Prepare(query string) (*Stmt, error) ``` Prepare准备一个专用于该事务的状态。返回的该事务专属状态操作在Tx递交会回滚后不能再使用。要在该事务中使用已存在的状态,参见Tx.Stmt方法。 ### func (\*Tx) [Stmt](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1149 "View Source") ``` func (tx *Tx) Stmt(stmt *Stmt) *Stmt ``` Stmt使用已存在的状态生成一个该事务特定的状态。 示例: ``` updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?") ... tx, err := db.Begin() ... res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203) ``` ### func (\*Tx) [Commit](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1075 "View Source") ``` func (tx *Tx) Commit() error ``` Commit递交事务。 ### func (\*Tx) [Rollback](https://github.com/golang/go/blob/master/src/database/sql/sql.go#L1086 "View Source") ``` func (tx *Tx) Rollback() error ``` Rollback放弃并回滚事务。