?
本文檔使用 php中文網(wǎng)手冊(cè) 發(fā)布
import "database/sql"
概述
索引
示例
子目錄
概述
Package sql 提供了一個(gè)圍繞SQL（或類(lèi)似SQL）數(shù)據(jù)庫(kù)的通用接口。
sql 包必須與數(shù)據(jù)庫(kù)驅(qū)動(dòng)程序一起使用。查看https://golang.org/s/sqldrivers獲取驅(qū)動(dòng)程序列表。
不支持上下文取消的驅(qū)動(dòng)程序直到查詢完成后才會(huì)返回。
有關(guān)使用示例，請(qǐng)參閱https://golang.org/s/sqlwiki上的wiki頁(yè)面。
索引
Variables
func Drivers() []string
func Register(name string, driver driver.Driver)
type ColumnType
func (ci *ColumnType) DatabaseTypeName() string
func (ci *ColumnType) DecimalSize() (precision, scale int64, ok bool)
func (ci *ColumnType) Length() (length int64, ok bool)
func (ci *ColumnType) Name() string
func (ci *ColumnType) Nullable() (nullable, ok bool)
func (ci *ColumnType) ScanType() reflect.Type
type Conn
func (c *Conn) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)
func (c *Conn) Close() error
func (c *Conn) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)
func (c *Conn) PingContext(ctx context.Context) error
func (c *Conn) PrepareContext(ctx context.Context, query string) (*Stmt, error)
func (c *Conn) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)
func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row
type DB
func Open(driverName, dataSourceName string) (*DB, error)
func (db *DB) Begin() (*Tx, error)
func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)
func (db *DB) Close() error
func (db *DB) Conn(ctx context.Context) (*Conn, error)
func (db *DB) Driver() driver.Driver
func (db *DB) Exec(query string, args ...interface{}) (Result, error)
func (db *DB) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)
func (db *DB) Ping() error
func (db *DB) PingContext(ctx context.Context) error
func (db *DB) Prepare(query string) (*Stmt, error)
func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error)
func (db *DB) Query(query string, args ...interface{}) (*Rows, error)
func (db *DB) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)
func (db *DB) QueryRow(query string, args ...interface{}) *Row
func (db *DB) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row
func (db *DB) SetConnMaxLifetime(d time.Duration)
func (db *DB) SetMaxIdleConns(n int)
func (db *DB) SetMaxOpenConns(n int)
func (db *DB) Stats() DBStats
type DBStats
type IsolationLevel
type NamedArg
func Named(name string, value interface{}) NamedArg
type NullBool
func (n *NullBool) Scan(value interface{}) error
func (n NullBool) Value() (driver.Value, error)
type NullFloat64
func (n *NullFloat64) Scan(value interface{}) error
func (n NullFloat64) Value() (driver.Value, error)
type NullInt64
func (n *NullInt64) Scan(value interface{}) error
func (n NullInt64) Value() (driver.Value, error)
type NullString
func (ns *NullString) Scan(value interface{}) error
func (ns NullString) Value() (driver.Value, error)
type Out
type RawBytes
type Result
type Row
func (r *Row) Scan(dest ...interface{}) error
type Rows
func (rs *Rows) Close() error
func (rs *Rows) ColumnTypes() ([]*ColumnType, error)
func (rs *Rows) Columns() ([]string, error)
func (rs *Rows) Err() error
func (rs *Rows) Next() bool
func (rs *Rows) NextResultSet() bool
func (rs *Rows) Scan(dest ...interface{}) error
type Scanner
type Stmt
func (s *Stmt) Close() error
func (s *Stmt) Exec(args ...interface{}) (Result, error)
func (s *Stmt) ExecContext(ctx context.Context, args ...interface{}) (Result, error)
func (s *Stmt) Query(args ...interface{}) (*Rows, error)
func (s *Stmt) QueryContext(ctx context.Context, args ...interface{}) (*Rows, error)
func (s *Stmt) QueryRow(args ...interface{}) *Row
func (s *Stmt) QueryRowContext(ctx context.Context, args ...interface{}) *Row
type Tx
func (tx *Tx) Commit() error
func (tx *Tx) Exec(query string, args ...interface{}) (Result, error)
func (tx *Tx) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)
func (tx *Tx) Prepare(query string) (*Stmt, error)
func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error)
func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error)
func (tx *Tx) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)
func (tx *Tx) QueryRow(query string, args ...interface{}) *Row
func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row
func (tx *Tx) Rollback() error
func (tx *Tx) Stmt(stmt *Stmt) *Stmt
func (tx *Tx) StmtContext(ctx context.Context, stmt *Stmt) *Stmt
type TxOptions
示例
DB.Query DB.QueryRow DB.Query (MultipleResultSets)
包文件
convert.go ctxutil.go sql.go
變量
在已經(jīng)提交或回滾的連接上執(zhí)行的任何操作都會(huì)返回 ErrConnDone。
var ErrConnDone = errors.New("database/sql: connection is already closed")當(dāng) QueryRow 沒(méi)有返回行時(shí)，Scan 返回 ErrNoRows。在這種情況下，QueryRow 會(huì)返回一個(gè)占位符* Row 值，該值將推遲發(fā)生此錯(cuò)誤直到掃描。
var ErrNoRows = errors.New("sql: no rows in result set")對(duì)已經(jīng)提交或回滾的事務(wù)執(zhí)行的任何操作都會(huì)返回 ErrTxDone。
var ErrTxDone = errors.New("sql: Transaction has already been committed or rolled back")func Drivers
func Drivers() []string
驅(qū)動(dòng)程序返回已注冊(cè)驅(qū)動(dòng)程序名稱(chēng)的排序列表。
func Register
func Register(name string, driver driver.Driver)
Register 使用提供的名稱(chēng)提供數(shù)據(jù)庫(kù)驅(qū)動(dòng)程序。如果使用相同的名稱(chēng)調(diào)用 Register 兩次，或者驅(qū)動(dòng)程序?yàn)榱悖瑒t會(huì)發(fā)生混亂。
type ColumnType
ColumnType 包含列的名稱(chēng)和類(lèi)型。
type ColumnType struct { // 包含過(guò)濾或未導(dǎo)出的字段}func (*ColumnType) DatabaseTypeName
func (ci *ColumnType) DatabaseTypeName() string
DatabaseTypeName 返回列類(lèi)型的數(shù)據(jù)庫(kù)系統(tǒng)名稱(chēng)。如果返回空字符串，則不支持驅(qū)動(dòng)程序類(lèi)型名稱(chēng)。請(qǐng)查閱您的驅(qū)動(dòng)程序文檔以獲取驅(qū)動(dòng)程序數(shù)據(jù)類(lèi)型列表 不包括長(zhǎng)度說(shuō)明符。常見(jiàn)類(lèi)型包括 “VARCHAR”，“TEXT”，“NVARCHAR”，“DECIMAL”，“BOOL”，“INT”，“BIGINT”。
func (*ColumnType) DecimalSize
func (ci *ColumnType) DecimalSize() (precision, scale int64, ok bool)
DecimalSize 返回小數(shù)類(lèi)型的比例和精度。如果不適用或者不支持，那么ok 是錯(cuò)誤的。
func (*ColumnType) Length
func (ci *ColumnType) Length() (length int64, ok bool)
Length 返回可變長(zhǎng)度列類(lèi)型（如文本和二進(jìn)制字段類(lèi)型）的列類(lèi)型長(zhǎng)度。如果類(lèi)型長(zhǎng)度沒(méi)有限制，則數(shù)值為 math.MaxInt64（任何數(shù)據(jù)庫(kù)限制仍將適用）。如果列類(lèi)型不是可變長(zhǎng)度，例如 int，或者如果驅(qū)動(dòng)程序不支持，那么 ok 是 false。
func (*ColumnType) Name
func (ci *ColumnType) Name() string
Name 返回列的名稱(chēng)或別名。
func (*ColumnType) Nullable
func (ci *ColumnType) Nullable() (nullable, ok bool)
Nullable 返回列是否可以為 null。如果一個(gè)驅(qū)動(dòng)程序不支持這個(gè)屬性，ok 將會(huì)是 false。
func (*ColumnType) ScanType
func (ci *ColumnType) ScanType() reflect.Type
ScanType 使用 Rows.Scan 返回適合掃描的 Go 類(lèi)型。如果驅(qū)動(dòng)程序不支持此屬性，ScanType 將返回空接口的類(lèi)型。
type Conn
Conn 代表一個(gè)數(shù)據(jù)庫(kù)會(huì)話而不是一個(gè)數(shù)據(jù)庫(kù)會(huì)話池。除非特別需要連續(xù)的單個(gè)數(shù)據(jù)庫(kù)會(huì)話，否則首選運(yùn)行 DB 查詢。
Conn 必須調(diào)用 Close 來(lái)將連接返回到數(shù)據(jù)庫(kù)池，并且可以與正在運(yùn)行的查詢同時(shí)進(jìn)行。
在調(diào)用 Close 之后，連接上的所有操作都會(huì)因 ErrConnDone 而失敗。
type Conn struct { // 包含過(guò)濾或未導(dǎo)出的字段}func (*Conn) BeginTx
func (c *Conn) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)
BeginTx 開(kāi)始一個(gè)交易。
提供的上下文用于事務(wù)提交或回滾之前。如果上下文被取消，sql包將回滾事務(wù)。如果提供給 BeginTx 的上下文被取消，則Tx.Commit 將返回錯(cuò)誤。
提供的 TxOptions 是可選的，如果應(yīng)該使用默認(rèn)值，則可能為零。如果使用驅(qū)動(dòng)程序不支持的非默認(rèn)隔離級(jí)別，則會(huì)返回錯(cuò)誤。
func (*Conn) Close
func (c *Conn) Close() error
Close 將連接返回到連接池。Close 后的所有操作都將返回ErrConnDone。Close 是安全地與其他操作同時(shí)進(jìn)行，并會(huì)阻止，直到所有其他操作完成。首先取消使用的上下文，然后直接調(diào)用 close 可能會(huì)很有用。
func (*Conn) ExecContext
func (c *Conn) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)ExecContext 執(zhí)行查詢而不返回任何行。該參數(shù)適用于查詢中的任何占位符參數(shù)。
func (*Conn) PingContext
func (c *Conn) PingContext(ctx context.Context) error
PingContext 驗(yàn)證到數(shù)據(jù)庫(kù)的連接是否仍然存在。
func (*Conn) PrepareContext
func (c *Conn) PrepareContext(ctx context.Context, query string) (*Stmt, error)
PrepareContext 為以后的查詢或執(zhí)行創(chuàng)建一個(gè)準(zhǔn)備好的語(yǔ)句?？梢詮姆祷氐恼Z(yǔ)句中同時(shí)運(yùn)行多個(gè)查詢或執(zhí)行。當(dāng)語(yǔ)句不再需要時(shí)，調(diào)用者必須調(diào)用語(yǔ)句的 Close 方法。
提供的上下文用于編寫(xiě)聲明，而不用于執(zhí)行聲明。
func (*Conn) QueryContext
func (c *Conn) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)QueryContext 執(zhí)行一個(gè)返回行的查詢，通常是一個(gè) SELECT。該參數(shù)適用于查詢中的任何占位符參數(shù)。
func (*Conn) QueryRowContext
func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...interface{}) *RowQueryRowContext 執(zhí)行一個(gè)預(yù)計(jì)最多只返回一行的查詢。QueryRowContext 總是返回一個(gè)非零值。錯(cuò)誤被推遲到行的掃描方法被調(diào)用。如果查詢未選擇行，則*Row 的掃描將返回錯(cuò)誤號(hào)。否則，*Row 的掃描將掃描第一個(gè)選定的行并丟棄其余行。
type DB
DB是一個(gè)數(shù)據(jù)庫(kù)句柄，表示一個(gè)包含零個(gè)或多個(gè)底層連接的池。多個(gè) goroutine 并發(fā)使用是安全的。
sql 包自動(dòng)創(chuàng)建并釋放連接；它也保持空閑連接的空閑池。如果數(shù)據(jù)庫(kù)具有每個(gè)連接狀態(tài)的概念，則只能在事務(wù)內(nèi)可靠地觀察到這種狀態(tài)。一旦 DB.Begin 被調(diào)用，返回的 Tx 就綁定到單個(gè)連接。在事務(wù)上調(diào)用 Commit 或 Rollback 后，該事務(wù)的連接將返回到數(shù)據(jù)庫(kù)的空閑連接池。池的大小可以通過(guò) SetMaxIdleConns 進(jìn)行控制。
type DB struct { // 包含過(guò)濾或未導(dǎo)出的字段}func Open
func Open(driverName, dataSourceName string) (*DB, error)
Open 打開(kāi)一個(gè)由其數(shù)據(jù)庫(kù)驅(qū)動(dòng)程序名稱(chēng)和驅(qū)動(dòng)程序特定的數(shù)據(jù)源名稱(chēng)指定的數(shù)據(jù)庫(kù)，通常由至少一個(gè)數(shù)據(jù)庫(kù)名稱(chēng)和連接信息組成。
大多數(shù)用戶將通過(guò)驅(qū)動(dòng)程序特定的連接幫助程序函數(shù)打開(kāi)數(shù)據(jù)庫(kù)，該函數(shù)返回一個(gè) *DB。Go標(biāo)準(zhǔn)庫(kù)中不包含數(shù)據(jù)庫(kù)驅(qū)動(dòng)程序。有關(guān)第三方驅(qū)動(dòng)程序的列表，請(qǐng)參閱https://golang.org/s/sqldrivers。
Open 可能只是驗(yàn)證其參數(shù)而不創(chuàng)建與數(shù)據(jù)庫(kù)的連接。要驗(yàn)證數(shù)據(jù)源名稱(chēng)是否有效，請(qǐng)調(diào)用 Ping。
返回的數(shù)據(jù)庫(kù)對(duì)于多個(gè) goroutine 的并發(fā)使用是安全的，并保持其自己的空閑連接池。因此，Open 函數(shù)應(yīng)該只調(diào)用一次。很少有必要關(guān)閉數(shù)據(jù)庫(kù)。
func (*DB) Begin
func (db *DB) Begin() (*Tx, error)
Begin 開(kāi)始一個(gè)交易。默認(rèn)隔離級(jí)別取決于驅(qū)動(dòng)程序。
func (*DB) BeginTx
func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)
BeginTx 開(kāi)始一個(gè)交易。
提供的上下文用于事務(wù)提交或回滾之前。如果上下文被取消，sql包將回滾事務(wù)。如果提供給 BeginTx 的上下文被取消，則Tx.Commit 將返回錯(cuò)誤。
提供的 TxOptions 是可選的，如果應(yīng)該使用默認(rèn)值，則可能為零。如果使用驅(qū)動(dòng)程序不支持的非默認(rèn)隔離級(jí)別，則會(huì)返回錯(cuò)誤。
func (*DB) Close
func (db *DB) Close() error
Close 關(guān)閉數(shù)據(jù)庫(kù)，釋放所有打開(kāi)的資源。
關(guān)閉數(shù)據(jù)庫(kù)是很少見(jiàn)的，因?yàn)閿?shù)據(jù)庫(kù)處理意味著很長(zhǎng)壽命并且在許多 goroutine 之間共享。
func (*DB) Conn
func (db *DB) Conn(ctx context.Context) (*Conn, error)
Conn 通過(guò)打開(kāi)新連接或從連接池返回現(xiàn)有連接返回單個(gè)連接。Conn 將阻塞，直到連接返回或 ctx 被取消。在同一個(gè) Conn 上運(yùn)行的查詢將在同一個(gè)數(shù)據(jù)庫(kù)會(huì)話中運(yùn)行。
通過(guò)調(diào)用 Conn.Close，每個(gè) Conn 必須在使用后返回到數(shù)據(jù)庫(kù)池。
func (*DB) Driver
func (db *DB) Driver() driver.Driver
Driver 返回?cái)?shù)據(jù)庫(kù)的底層驅(qū)動(dòng)程序。
func (*DB) Exec
func (db *DB) Exec(query string, args ...interface{}) (Result, error)Exec 執(zhí)行查詢而不返回任何行。該參數(shù)適用于查詢中的任何占位符參數(shù)。
func (*DB) ExecContext
func (db *DB) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)ExecContext 執(zhí)行查詢而不返回任何行。該參數(shù)適用于查詢中的任何占位符參數(shù)。
func (*DB) Ping
func (db *DB) Ping() error
Ping 驗(yàn)證與數(shù)據(jù)庫(kù)的連接仍然存在，并在必要時(shí)建立連接。
func (*DB) PingContext
func (db *DB) PingContext(ctx context.Context) error
PingContext 驗(yàn)證與數(shù)據(jù)庫(kù)的連接是否仍然存在，如果需要的話建立連接。
func (*DB) Prepare
func (db *DB) Prepare(query string) (*Stmt, error)
Prepare 為以后的查詢或執(zhí)行創(chuàng)建一個(gè)準(zhǔn)備好的語(yǔ)句?？梢詮姆祷氐恼Z(yǔ)句中同時(shí)運(yùn)行多個(gè)查詢或執(zhí)行。當(dāng)語(yǔ)句不再需要時(shí)，調(diào)用者必須調(diào)用語(yǔ)句的 Close 方法。
func (*DB) PrepareContext
func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error)
PrepareContext 為以后的查詢或執(zhí)行創(chuàng)建一個(gè)準(zhǔn)備好的語(yǔ)句。可以從返回的語(yǔ)句中同時(shí)運(yùn)行多個(gè)查詢或執(zhí)行。當(dāng)語(yǔ)句不再需要時(shí)，調(diào)用者必須調(diào)用語(yǔ)句的 Close 方法。
提供的上下文用于編寫(xiě)聲明，而不用于執(zhí)行聲明。
func (*DB) Query
func (db *DB) Query(query string, args ...interface{}) (*Rows, error)查詢執(zhí)行一個(gè)返回行的查詢，通常是一個(gè) SELECT。該參數(shù)適用于查詢中的任何占位符參數(shù)。
示例
代碼：
age := 27rows, 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)}示例（MultipleResultSets）
代碼:
age := 27q := `
create temp table uid (id bigint); -- Create temp table for queries.
insert into uid
select id from users where age < ?; -- Populate temp table.
-- First result set.
select
users.id, name
from
users
join uid on users.id = uid.id
;
-- Second result set.
select
ur.user, ur.role
from
user_roles as ur
join uid on uid.id = ur.user
;
`rows, err := db.Query(q, age)if err != nil {
log.Fatal(err)}defer rows.Close()for rows.Next() { var (
id int64
name string ) if err := rows.Scan(&id, &name); err != nil {
log.Fatal(err) }
fmt.Printf("id %d name is %s\n", id, name)}if !rows.NextResultSet() {
log.Fatal("expected more result sets", rows.Err())}var roleMap = map[int64]string{ 1: "user", 2: "admin", 3: "gopher",}for rows.Next() { var (
id int64
role int64 ) if err := rows.Scan(&id, &role); err != nil {
log.Fatal(err) }
fmt.Printf("id %d has role %s\n", id, roleMap[role])}if err := rows.Err(); err != nil {
log.Fatal(err)}func (*DB) QueryContext
func (db *DB) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)QueryContext 執(zhí)行一個(gè)返回行的查詢，通常是一個(gè) SELECT。該參數(shù)適用于查詢中的任何占位符參數(shù)。
func (*DB) QueryRow
func (db *DB) QueryRow(query string, args ...interface{}) *RowQueryRow 執(zhí)行一個(gè)查詢，該查詢最多只返回一行。QueryRow總是返回一個(gè)非零值。錯(cuò)誤被推遲到行的掃描方法被調(diào)用。如果查詢未選擇行，則*Row 的掃描將返回錯(cuò)誤號(hào)。否則，*Row 的掃描將掃描第一個(gè)選定的行并丟棄其余行。
示例
代碼：
id := 123var 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) QueryRowContext
func (db *DB) QueryRowContext(ctx context.Context, query string, args ...interface{}) *RowQueryRowContext 執(zhí)行一個(gè)預(yù)計(jì)最多只返回一行的查詢。QueryRowContext 總是返回一個(gè)非零值。錯(cuò)誤被推遲到行的掃描方法被調(diào)用。如果查詢未選擇行，則*Row 的掃描將返回錯(cuò)誤號(hào)。否則，*Row 的掃描將掃描第一個(gè)選定的行并丟棄其余行。
func (*DB) SetConnMaxLifetime
func (db *DB) SetConnMaxLifetime(d time.Duration)
SetConnMaxLifetime 設(shè)置連接可以被重用的最大時(shí)間量。
過(guò)期的連接可能會(huì)在重用之前被緩慢地關(guān)閉。
如果d <= 0，連接將永久重用。
func (*DB) SetMaxIdleConns
func (db *DB) SetMaxIdleConns(n int)
SetMaxIdleConns 設(shè)置空閑連接池中的最大連接數(shù)。
如果 MaxOpenConns 大于0但小于新的 MaxIdleConns，那么新的 MaxIdleConns 將減少以匹配 MaxOpenConns 限制
如果n <= 0，則不保留空閑連接。
func (*DB) SetMaxOpenConns
func (db *DB) SetMaxOpenConns(n int)
SetMaxOpenConns 設(shè)置打開(kāi)到數(shù)據(jù)庫(kù)的最大連接數(shù)。
如果 MaxIdleConns 大于0并且新的 MaxOpenConns 小于MaxIdleConns，則 MaxIdleConns 將減少以匹配新的MaxOpenConns 限制
如果n <= 0，那么打開(kāi)連接的數(shù)量沒(méi)有限制。默認(rèn)值是0（無(wú)限制）。
func (*DB) Stats
func (db *DB) Stats() DBStats
Stats 返回?cái)?shù)據(jù)庫(kù)統(tǒng)計(jì)信息
type DBStats
DBStats 包含數(shù)據(jù)庫(kù)統(tǒng)計(jì)信息。
type DBStats struct { // OpenConnections是打開(kāi)連接到數(shù)據(jù)庫(kù)的數(shù)量。
OpenConnections int}type IsolationLevel
IsolationLevel 是 TxOptions 中使用的事務(wù)隔離級(jí)別。
type IsolationLevel int
BeginTx 中驅(qū)動(dòng)程序可能支持的各種隔離級(jí)別。如果驅(qū)動(dòng)程序不支持給定的隔離級(jí)別，則可能會(huì)返回錯(cuò)誤。
參見(jiàn)https://en.wikipedia.org/wiki/Isolation_（database_systems）#Isolation_levels（https://en.wikipedia.org/wiki/Isolation_（database_systems％29個(gè)＃Isolation_levels）。
const ( LevelDefault IsolationLevel = iota LevelReadUncommitted LevelReadCommitted LevelWriteCommitted LevelRepeatableRead LevelSnapshot LevelSerializable LevelLinearizable)
type NamedArg
NamedArg 是一個(gè)命名參數(shù)。NamedArg 值可以用作 Query 或Exec 的參數(shù)，并綁定到 SQL 語(yǔ)句中的相應(yīng)命名參數(shù)。
有關(guān)創(chuàng)建 NamedArg 值的更簡(jiǎn)潔的方法，請(qǐng)參閱 Named 函數(shù)。
type NamedArg struct { // Name是參數(shù)占位符的名稱(chēng)。 // // 如果為空，參數(shù)列表中的序號(hào)位置將為 // 被使用。 // // 名稱(chēng)必須省略任何符號(hào)前綴。
Name string // 值是參數(shù)的值。 // 它可以被分配與查詢相同的值類(lèi)型 // 參數(shù)。
Value interface{} // 包含過(guò)濾或未導(dǎo)出的字段}func Named
func Named(name string, value interface{}) NamedArgNamed 提供了一種更簡(jiǎn)潔的方式來(lái)創(chuàng)建 NamedArg 值。
用法示例：
db.ExecContext(ctx, `
delete from Invoice
where
TimeCreated < @end
and TimeCreated >= @start;`,
sql.Named("start", startTime),
sql.Named("end", endTime),)type NullBool
NullBool 表示一個(gè)可能為 null 的布爾值。NullBool 實(shí)現(xiàn)了Scanner 接口，因此它可以用作掃描目標(biāo)，類(lèi)似于 NullString。
type NullBool struct {
Bool bool
Valid bool // 如果Bool不為NULL，則有效為真}func (*NullBool) Scan
func (n *NullBool) Scan(value interface{}) errorScan 實(shí)現(xiàn)掃描儀界面。
func (NullBool) Value
func (n NullBool) Value() (driver.Value, error)
Value 實(shí)現(xiàn)了驅(qū)動(dòng) Valuer 接口。
type NullFloat64
NullFloat64 表示可能為 null 的 float64。NullFloat64 實(shí)現(xiàn)了掃描器接口，因此它可以用作掃描目標(biāo)，類(lèi)似于 NullString。
type NullFloat64 struct {
Float64 float64
Valid bool //如果Float64不為NULL，則有效}func (*NullFloat64) Scan
func (n *NullFloat64) Scan(value interface{}) errorScan 實(shí)現(xiàn)掃描儀界面。
func (NullFloat64) Value
func (n NullFloat64) Value() (driver.Value, error)
Value 實(shí)現(xiàn)了驅(qū)動(dòng) Valuer 接口。
type NullInt64
NullInt64 代表可能為 null 的 int64。NullInt64 實(shí)現(xiàn)了掃描器接口，因此它可以用作掃描目標(biāo)，類(lèi)似于 NullString。
type NullInt64 struct {
Int64 int64
Valid bool // 如果Int64不為NULL，則有效為真}func (*NullInt64) Scan
func (n *NullInt64) Scan(value interface{}) errorScan 實(shí)現(xiàn)掃描儀界面。
func (NullInt64) Value
func (n NullInt64) Value() (driver.Value, error)
Value 實(shí)現(xiàn)了驅(qū)動(dòng) Valuer 接口。
type NullString
NullString 表示一個(gè)可能為空的字符串。NullString 實(shí)現(xiàn)了掃描器接口，因此它可以用作掃描目標(biāo)：
var s NullString
err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s)...if s.Valid { // 使用 s.String} else { // NULL值（空值）}type NullString struct {
String string
Valid bool // 如果String不為NULL，則有效值為true}func (*NullString) Scan
func (ns *NullString) Scan(value interface{}) errorScan 實(shí)現(xiàn)掃描儀界面。
func (NullString) Value
func (ns NullString) Value() (driver.Value, error)
Value 實(shí)現(xiàn)了驅(qū)動(dòng) Valuer 接口。
type Out
Out 可用于從存儲(chǔ)過(guò)程中檢索 OUTPUT 值參數(shù)。
并非所有驅(qū)動(dòng)程序和數(shù)據(jù)庫(kù)都支持 OUTPUT 值參數(shù)。
用法示例：
var outArg string
_, err := db.ExecContext(ctx, "ProcName", sql.Named("Arg1", Out{Dest: &outArg}))type Out struct { // Dest是指向?qū)⒈辉O(shè)置為結(jié)果的值的指針 // 存儲(chǔ)過(guò)程O(píng)UTPUT參數(shù)。
Dest interface{} // In是參數(shù)是否是INOUT參數(shù)。 如果是這樣，輸入值存儲(chǔ) // 過(guò)程是Dest指針的取消引用值，然后將其替換為 // 輸出值。
In bool // 包含過(guò)濾或未導(dǎo)出的字段}type RawBytes
RawBytes 是一個(gè)字節(jié)片段，用于保存對(duì)數(shù)據(jù)庫(kù)本身?yè)碛械膬?nèi)存的引用。在掃描到 RawBytes 之后，切片只有在下一次調(diào)用 Next，Scan 或 Close 時(shí)才有效。
type RawBytes []byte
type Result
Result 匯總了執(zhí)行的 SQL 命令。
type Result interface { // LastInsertId返回?cái)?shù)據(jù)庫(kù)生成的整數(shù) // 以響應(yīng)命令。 通常這將來(lái)自 // 插入新行時(shí)的“自動(dòng)增量（auto increment）”列。 并非全部 // 數(shù)據(jù)庫(kù)支持這個(gè)功能，以及這樣的語(yǔ)法 // 聲明各不相同 LastInsertId() (int64, error) // RowsAffected返回受影響的行數(shù) // 更新，插入或刪除。 不是每個(gè)數(shù)據(jù)庫(kù)或數(shù)據(jù)庫(kù) // 驅(qū)動(dòng)可能會(huì)支持這個(gè)。 RowsAffected() (int64, error)}type Row
Row 是調(diào)用 QueryRow 選擇單個(gè)行的結(jié)果。
type Row struct { // 包含過(guò)濾或未導(dǎo)出的字段}func (*Row) Scan
func (r *Row) Scan(dest ...interface{}) errorScan 將匹配行中的列復(fù)制到 dest 指向的值中。有關(guān)詳細(xì)信息，請(qǐng)參閱 Rows.Scan 上的文檔。如果多個(gè)行與查詢匹配，則 Scan 使用第一行并丟棄其余行。如果沒(méi)有行與查詢匹配，則 Scan 會(huì)返回 ErrNoRows。
type Rows
Rows 是查詢的結(jié)果。它的游標(biāo)在結(jié)果集的第一行之前開(kāi)始。使用下一步在行中前進(jìn)：
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() // 獲取迭代期間遇到的任何錯(cuò)誤type Rows struct { // 包含過(guò)濾或未導(dǎo)出的字段}func (*Rows) Close
func (rs *Rows) Close() error
Close 關(guān)閉行，防止進(jìn)一步枚舉。如果 Next 被調(diào)用并返回false，并且沒(méi)有其他結(jié)果集，則行自動(dòng)關(guān)閉，并且檢查 Err 的結(jié)果就足夠了。關(guān)閉是冪等的，不會(huì)影響 Err 的結(jié)果。
func (*Rows) ColumnTypes
func (rs *Rows) ColumnTypes() ([]*ColumnType, error)
ColumnTypes 返回列信息，如列類(lèi)型，長(zhǎng)度和空值。某些驅(qū)動(dòng)程序可能無(wú)法提供某些信息。
func (*Rows) Columns
func (rs *Rows) Columns() ([]string, error)
列將返回列名稱(chēng)。如果行關(guān)閉，或者行來(lái)自 QueryRow 并且存在延遲錯(cuò)誤，則列將返回錯(cuò)誤。
func (*Rows) Err
func (rs *Rows) Err() error
Err 會(huì)返回在迭代期間遇到的錯(cuò)誤（如果有的話）。Err 可能會(huì)在顯式或隱式關(guān)閉后調(diào)用。
func (*Rows) Next
func (rs *Rows) Next() bool
接下來(lái)準(zhǔn)備下一個(gè)結(jié)果行以便用 Scan 方法讀取。它在成功時(shí)返回 true，如果沒(méi)有下一個(gè)結(jié)果行或在準(zhǔn)備過(guò)程中發(fā)生錯(cuò)誤，則返回 false。應(yīng)該咨詢 Err 以區(qū)分這兩種情況。
每次調(diào)用 Scan，即使是第一次，都必須先調(diào)用 Next。
func (*Rows) NextResultSet
func (rs *Rows) NextResultSet() bool
NextResultSet 準(zhǔn)備下一個(gè)讀取結(jié)果集。如果有進(jìn)一步的結(jié)果集，則返回 true；如果沒(méi)有進(jìn)一步的結(jié)果集或者有錯(cuò)誤前進(jìn)，則返回 false。應(yīng)該參考 Err 方法來(lái)區(qū)分這兩種情況。
在調(diào)用 NextResultSet 之后，應(yīng)始終在掃描之前調(diào)用 Next 方法。如果有更多的結(jié)果集，它們?cè)诮Y(jié)果集中可能沒(méi)有行。
func (*Rows) Scan
func (rs *Rows) Scan(dest ...interface{}) errorScan 將當(dāng)前行中的列復(fù)制到dest指向的值中。dest 中的值數(shù)量必須與行中的列數(shù)相同。
Scan 將從數(shù)據(jù)庫(kù)讀取的列轉(zhuǎn)換為以下常見(jiàn)的 Go 類(lèi)型和 sql 包提供的特殊類(lèi)型：
*string*[]byte*int, *int8, *int16, *int32, *int64*uint, *uint8, *uint16, *uint32, *uint64*bool*float32, *float64*interface{}*RawBytes
any type implementing Scanner (see Scanner docs)在最簡(jiǎn)單的情況下，如果源列中的值的類(lèi)型是整數(shù)，bool 或字符串類(lèi)型 T 和 dest 的類(lèi)型是 *T，則 Scan 只是通過(guò)指針?lè)峙渲怠?/p>
Scan 也可以在字符串和數(shù)字類(lèi)型之間進(jìn)行轉(zhuǎn)換，只要不會(huì)丟失任何信息。當(dāng)Scan 將從數(shù)字?jǐn)?shù)據(jù)庫(kù)列掃描的所有數(shù)字串化為*字符串時(shí)，將掃描為數(shù)字類(lèi)型進(jìn)行溢出檢查。例如，值為300的float64 或值為“300”的字符串可以掃描到 uint16，但不能掃描到uint8，但 float64(255)或“255”可掃描到uint8。一個(gè)例外是某些 float64 數(shù)字字符串的掃描可能會(huì)在字符串化時(shí)丟失信息。通常，將浮點(diǎn)列掃描到 *float64。
如果 dest 參數(shù)的類(lèi)型為 *[]byte，則 Scan 會(huì)在該參數(shù)中保存相應(yīng)數(shù)據(jù)的副本。副本由調(diào)用者擁有，可以無(wú)限期修改和保存。可以通過(guò)使用類(lèi)型 *RawBytes 的參數(shù)來(lái)避免該副本；請(qǐng)參閱 RawBytes 的文檔以了解其使用限制。
如果參數(shù)具有類(lèi)型 *interface{}，則掃描會(huì)復(fù)制底層驅(qū)動(dòng)程序提供的值而不進(jìn)行轉(zhuǎn)換。從類(lèi)型 []byte 的源值掃描到 *interface{}時(shí)，會(huì)創(chuàng)建片的副本，并且調(diào)用者擁有結(jié)果。
時(shí)間類(lèi)型的源值可以被掃描為類(lèi)型 *time.Time， *interface {}，*string 或 *[]byte 的值。當(dāng)轉(zhuǎn)換到后兩者時(shí)，使用 time.Format3339Nano。
可以將bool類(lèi)型的源值掃描到*bool，*interface {}，*string，*[]字節(jié)或 *RawBytes 類(lèi)型中。
對(duì)于掃描到 *bool，源可能是true，false，1，0或 strconv.ParseBool 可解析的字符串輸入。
type Scanner
Scanner 是 Scan 使用的接口。
type Scanner interface { // 掃描從數(shù)據(jù)庫(kù)驅(qū)動(dòng)程序分配一個(gè)值。 // // src值將是以下類(lèi)型之一： // // int64 // float64 // bool // []byte // string // time.Time // nil - for NULL values // // 如果該值無(wú)法存儲(chǔ)，則應(yīng)返回錯(cuò)誤 // 而不會(huì)丟失信息。 Scan(src interface{}) error}type Stmt
Stmt 是一個(gè)準(zhǔn)備好的聲明。Stmt 對(duì)于多個(gè) goroutines 并發(fā)使用是安全的。
type Stmt struct { // 包含過(guò)濾或未導(dǎo)出的字段}func (*Stmt) Close
func (s *Stmt) Close() error
Close 關(guān)閉聲明。
func (*Stmt) Exec
func (s *Stmt) Exec(args ...interface{}) (Result, error)Exec 使用給定的參數(shù)執(zhí)行一個(gè)準(zhǔn)備好的語(yǔ)句，并返回一個(gè)總結(jié)語(yǔ)句效果的 Result 。
func (*Stmt) ExecContext
func (s *Stmt) ExecContext(ctx context.Context, args ...interface{}) (Result, error)ExecContext 使用給定的參數(shù)執(zhí)行一個(gè)準(zhǔn)備好的語(yǔ)句，并返回一個(gè)總結(jié)語(yǔ)句效果的 Result 。
func (*Stmt) Query
func (s *Stmt) Query(args ...interface{}) (*Rows, error)查詢使用給定的參數(shù)執(zhí)行準(zhǔn)備好的查詢語(yǔ)句，并將查詢結(jié)果作為 *Row 返回。
func (*Stmt) QueryContext
func (s *Stmt) QueryContext(ctx context.Context, args ...interface{}) (*Rows, error)QueryContext 使用給定的參數(shù)執(zhí)行準(zhǔn)備好的查詢語(yǔ)句，并將查詢結(jié)果作為 *Row 返回。
func (*Stmt) QueryRow
func (s *Stmt) QueryRow(args ...interface{}) *RowQueryRow 使用給定的參數(shù)執(zhí)行一個(gè)準(zhǔn)備好的查詢語(yǔ)句。如果在執(zhí)行語(yǔ)句期間發(fā)生錯(cuò)誤，則在返回的 *Row 上調(diào)用 Scan 以返回該錯(cuò)誤，該行總是非零。如果查詢未選擇行，則*Row 的掃描將返回錯(cuò)誤號(hào)。否則，*Row 的掃描將掃描第一個(gè)選定的行并丟棄其余行。
用法示例：
var name string err := nameByUseridStmt.QueryRow(id).Scan(&name)
func (*Stmt) QueryRowContext
func (s *Stmt) QueryRowContext(ctx context.Context, args ...interface{}) *RowQueryRowContext 使用給定的參數(shù)執(zhí)行準(zhǔn)備好的查詢語(yǔ)句。如果在執(zhí)行語(yǔ)句期間發(fā)生錯(cuò)誤，則在返回的 *Row 上調(diào)用 Scan 以返回該錯(cuò)誤，該行總是非零。如果查詢未選擇行，則 *Row 的掃描將返回錯(cuò)誤號(hào)。否則，*Row 的掃描將掃描第一個(gè)選定的行并丟棄其余行。
用法示例：
var name string err := nameByUseridStmt.QueryRowContext(ctx, id).Scan(&name)
type Tx
Tx 是正在進(jìn)行的數(shù)據(jù)庫(kù)事務(wù)。
Transaction 必須以對(duì) Commit 或 Rollback 的調(diào)用結(jié)束。
在調(diào)用 Commit 或 Rollback 之后，事務(wù)上的所有操作都會(huì)因ErrTxDone 而失敗。
通過(guò)調(diào)用事務(wù)的 Prepare 或 Stmt 方法為事務(wù)準(zhǔn)備的語(yǔ)句通過(guò)對(duì)Commit 或 Rollback 的調(diào)用關(guān)閉。
type Tx struct { // 包含過(guò)濾或未導(dǎo)出的字段}func (*Tx) Commit
func (tx *Tx) Commit() error
Commit 提交事務(wù)（transaction）。
func (*Tx) Exec
func (tx *Tx) Exec(query string, args ...interface{}) (Result, error)Exec 執(zhí)行不返回行的查詢。例如：INSERT 和 UPDATE。
func (*Tx) ExecContext
func (tx *Tx) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)ExecContext 執(zhí)行不返回行的查詢。例如：INSERT 和 UPDATE。
func (*Tx) Prepare
func (tx *Tx) Prepare(query string) (*Stmt, error)
Prepare 創(chuàng)建一個(gè)準(zhǔn)備好的語(yǔ)句，以便在事務(wù)中使用。
返回的語(yǔ)句在事務(wù)內(nèi)運(yùn)行，并且一旦事務(wù)被提交或回滾就不能再使用。
要在此事務(wù)中使用現(xiàn)有的準(zhǔn)備語(yǔ)句，請(qǐng)參閱 Tx.Stmt。
func (*Tx) PrepareContext
func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error)
PrepareContext 在事務(wù)中創(chuàng)建一個(gè)準(zhǔn)備好的語(yǔ)句。
返回的語(yǔ)句在事務(wù)內(nèi)運(yùn)行，并在事務(wù)提交或回滾時(shí)關(guān)閉。
要在此事務(wù)中使用現(xiàn)有的準(zhǔn)備語(yǔ)句，請(qǐng)參閱 Tx.Stmt。
提供的上下文將用于準(zhǔn)備上下文，而不用于執(zhí)行返回的語(yǔ)句。返回的語(yǔ)句將在事務(wù)上下文中運(yùn)行。
func (*Tx) Query
func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error)查詢執(zhí)行一個(gè)返回行的查詢，通常是一個(gè) SELECT。
func (*Tx) QueryContext
func (tx *Tx) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)QueryContext 執(zhí)行一個(gè)返回行的查詢，通常是一個(gè) SELECT。
func (*Tx) QueryRow
func (tx *Tx) QueryRow(query string, args ...interface{}) *RowQueryRow 執(zhí)行一個(gè)查詢，該查詢最多只返回一行。QueryRow 總是返回一個(gè)非零值。錯(cuò)誤被推遲到行的掃描方法被調(diào)用。如果查詢未選擇行，則*Row 的掃描將返回錯(cuò)誤號(hào)。否則，*Row 的掃描將掃描第一個(gè)選定的行并丟棄其余行。
func (*Tx) QueryRowContext
func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...interface{}) *RowQueryRowContext 執(zhí)行一個(gè)預(yù)計(jì)最多只返回一行的查詢。QueryRowContext 總是返回一個(gè)非零值。錯(cuò)誤被推遲到行的掃描方法被調(diào)用。如果查詢未選擇行，則*Row 的掃描將返回錯(cuò)誤號(hào)。否則，*Row 的掃描將掃描第一個(gè)選定的行并丟棄其余行。
func (*Tx) Rollback
func (tx *Tx) Rollback() error
Rollback 將中止事務(wù)。
func (*Tx) Stmt
func (tx *Tx) Stmt(stmt *Stmt) *Stmt
Stmt 從現(xiàn)有的語(yǔ)句中返回特定于事務(wù)的預(yù)處理語(yǔ)句。
例子：
updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")...tx, err := db.Begin()...res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203)返回的語(yǔ)句在事務(wù)內(nèi)運(yùn)行，并在事務(wù)提交或回滾時(shí)關(guān)閉。
func (*Tx) StmtContext
func (tx *Tx) StmtContext(ctx context.Context, stmt *Stmt) *Stmt
StmtContext 從現(xiàn)有語(yǔ)句中返回特定于事務(wù)的預(yù)處理語(yǔ)句。
示例：
updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")...tx, err := db.Begin()...res, err := tx.StmtContext(ctx, updateMoney).Exec(123.45, 98293203)返回的語(yǔ)句在事務(wù)內(nèi)運(yùn)行，并在事務(wù)提交或回滾時(shí)關(guān)閉。
type TxOptions
TxOptions 保存要在 DB.BeginTx 中使用的事務(wù)選項(xiàng)。
type TxOptions struct { // 隔離（Isolation）是事務(wù)隔離級(jí)別。 // 如果為零，則使用驅(qū)動(dòng)程序或數(shù)據(jù)庫(kù)的默認(rèn)級(jí)別。
Isolation IsolationLevel
ReadOnly bool}子目錄
名稱(chēng) | 概要 |
|---|---|
| 驅(qū)動(dòng)程序| | 軟件包驅(qū)動(dòng)程序定義由 sql 包使用的數(shù)據(jù)庫(kù)驅(qū)動(dòng)程序?qū)崿F(xiàn)的接口。 |