• import "database/sql/driver"

• 概述

• 索引

概述

軟件包驅(qū)動(dòng)程序定義由 sql 包使用的數(shù)據(jù)庫(kù)驅(qū)動(dòng)程序?qū)崿F(xiàn)的接口。

大多數(shù)代碼應(yīng)該使用 sql包 。

索引

• 變量（Variables）

• func IsScanValue(v interface{}) bool

• func IsValue(v interface{}) bool

• type ColumnConverter

• type Conn

• type ConnBeginTx

• type ConnPrepareContext

• type Driver

• type Execer

• type ExecerContext

• type IsolationLevel

• type NamedValue

• type NamedValueChecker

• type NotNull

• func (n NotNull) ConvertValue(v interface{}) (Value, error)

• type Null

• func (n Null) ConvertValue(v interface{}) (Value, error)

• type Pinger

• type Queryer

• type QueryerContext

• type Result

• type Rows

• type RowsAffected

• func (RowsAffected) LastInsertId() (int64, error)

• func (v RowsAffected) RowsAffected() (int64, error)

• type RowsColumnTypeDatabaseTypeName

• type RowsColumnTypeLength

• type RowsColumnTypeNullable

• type RowsColumnTypePrecisionScale

• type RowsColumnTypeScanType

• type RowsNextResultSet

• type Stmt

• type StmtExecContext

• type StmtQueryContext

• type Tx

• type TxOptions

• type Value

• type ValueConverter

• type Valuer

包文件

driver.go types.go

變量

Bool 是一個(gè)將輸入值轉(zhuǎn)換為布爾值的 ValueConverter。

轉(zhuǎn)換規(guī)則是：

 - 布爾值不變- 對(duì)于整數(shù)類型，     1是真的     0是假的，
     其他整數(shù)是一個(gè)錯(cuò)誤- 對(duì)于字符串和[]字節(jié)，與strconv.ParseBool相同的規(guī)則- 所有其他類型都是錯(cuò)誤的

var Bool boolType

DefaultParameterConverter 是當(dāng) Stmt 沒有實(shí)現(xiàn)ColumnConverter 時(shí)使用的 ValueConverter 的默認(rèn)實(shí)現(xiàn)。

如果是 IsValue(arg)，DefaultParameterConverter 直接返回它的參數(shù)。否則，如果參數(shù)實(shí)現(xiàn)了 Valuer，則其 Value 方法用于返回值。作為回退，所提供的參數(shù)的基礎(chǔ)類型用于將其轉(zhuǎn)換為值：基礎(chǔ)整數(shù)類型轉(zhuǎn)換為 int64，浮動(dòng)到 float64，bool，string 和 []byte。如果參數(shù)是一個(gè)零指針，ConvertValue 返回一個(gè)零值。如果參數(shù)是一個(gè)非零指針，則將其解除引用，并且遞歸地調(diào)用 ConvertValue 。其他類型是錯(cuò)誤的。

var DefaultParameterConverter defaultConverter

ErrBadConn 應(yīng)由驅(qū)動(dòng)程序返回以向 sql 包發(fā)出信號(hào)，指出driver.Conn 處于不良狀態(tài)（例如服務(wù)器先前已關(guān)閉連接），并且 sql 包應(yīng)該在新連接上重試。

為防止重復(fù)操作，如果數(shù)據(jù)庫(kù)服務(wù)器可能執(zhí)行了操作，則不應(yīng)返回 ErrBadConn。即使服務(wù)器發(fā)回錯(cuò)誤，也不應(yīng)返回 ErrBadConn。

var ErrBadConn = errors.New("driver: bad connection")

可以從 NamedValueChecker 返回 ErrRemoveArgument 以指示 sql 包不將參數(shù)傳遞給驅(qū)動(dòng)程序查詢接口。當(dāng)接受查詢特定選項(xiàng)或不是 SQL 查詢參數(shù)的結(jié)構(gòu)時(shí)返回。

var ErrRemoveArgument = errors.New("driver: remove argument from query")

ErrSkip 可能會(huì)由一些可選接口的方法返回，以在運(yùn)行時(shí)指示快速路徑不可用，并且 sql 包應(yīng)繼續(xù)，就好像可選接口未實(shí)現(xiàn)一樣。ErrSkip 僅在明確記錄的情況下才受支持。

var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")

Int32 是一個(gè) ValueConverter，它將輸入值轉(zhuǎn)換為 int64 ，并考慮到 int32 值的限制。

var Int32 int32Type

ResultNoRows 是驅(qū)動(dòng)程序在 DDL 命令（例如 CREATE TABLE）成功時(shí)返回的預(yù)定義結(jié)果。它為 LastInsertId 和RowsAffected 都返回一個(gè)錯(cuò)誤。

var ResultNoRows noRows

字符串是一個(gè)將其輸入轉(zhuǎn)換為字符串的 ValueConverter。如果該值已經(jīng)是字符串或[]字節(jié)，則不會(huì)改變。如果該值是另一種類型，則使用 fmt.Sprintf（“％v”,v）完成對(duì)字符串的轉(zhuǎn)換。

var String stringType

func IsScanValue

func IsScanValue(v interface{}) bool

IsScanValue 等同于 IsValue。它存在的兼容性。

func IsValue

func IsValue(v interface{}) bool

IsValue 報(bào)告 v 是否是有效的 Value 參數(shù)類型。

type ColumnConverter

如果語句知道它自己的列的類型并且可以從任何類型轉(zhuǎn)換為驅(qū)動(dòng)程序的值，那么 ColumnConverter 可以選擇由 Stmt 實(shí)現(xiàn)。

不推薦使用：驅(qū)動(dòng)程序應(yīng)該實(shí)現(xiàn) NamedValueChecker 。

type ColumnConverter interface {        // ColumnConverter為所提供的返回一個(gè)ValueConverter        // 列索引（column index）。 如果特定列的類型未知        // 或者不應(yīng)該專門處理，DefaultValueConverter        // 可以返回。        ColumnConverter(idx int) ValueConverter}

type Conn

Conn 是與數(shù)據(jù)庫(kù)的連接。它不是由多個(gè) goroutine 同時(shí)使用。

Conn 被認(rèn)為是有狀態(tài)的。

type Conn interface {        // Prepare返回一個(gè)準(zhǔn)備好的語句，綁定到這個(gè)連接。        Prepare(query string) (Stmt, error)        // Close無效并可能停止任何當(dāng)前        // 準(zhǔn)備好的陳述和交易，標(biāo)記這一點(diǎn)        // 連接不再使用。        //        // 因?yàn)閟ql包維護(hù)著一個(gè)空閑的池        // 連接和只有調(diào)用在有剩余時(shí)關(guān)閉        // 空閑的連接，它不應(yīng)該是驅(qū)動(dòng)程序需要        // 做自己的連接緩存。        Close() error        // 開始并返回一個(gè)新的事務(wù)。        //        // 不推薦使用：驅(qū)動(dòng)程序應(yīng)該（或另外）實(shí)現(xiàn)ConnBeginTx。        Begin() (Tx, error)}

type ConnBeginTx

ConnBeginTx 通過上下文和 TxOptions 增強(qiáng)了 Conn 接口。

type ConnBeginTx interface {        // BeginTx啟動(dòng)并返回一個(gè)新的事務(wù)。        // 如果上下文被用戶取消，那么sql包會(huì)        // 在丟棄和關(guān)閉連接之前調(diào)用Tx.Rollback。        //        // 這必須檢查opts.Isolation以確定是否有一個(gè)集合        // 隔離級(jí)別。 如果驅(qū)動(dòng)程序不支持非默認(rèn)        // 級(jí)別和一個(gè)設(shè)置，或者如果有一個(gè)非默認(rèn)的隔離級(jí)別        // 如果不支持，則必須返回錯(cuò)誤。        //        // 這還必須檢查opts.ReadOnly以確定是否只讀        // 如果支持，則設(shè)置只讀事務(wù)屬性的值為true        // 或者如果不支持則返回錯(cuò)誤。        BeginTx(ctx context.Context, opts TxOptions) (Tx, error)}

type ConnPrepareContext

ConnPrepareContext 通過上下文增強(qiáng)了 Conn 接口。

type ConnPrepareContext interface {        // PrepareContext返回一個(gè)準(zhǔn)備好的語句，綁定到這個(gè)連接。        // context是編寫聲明，        // 它不能在語句本身內(nèi)存儲(chǔ)上下文。        PrepareContext(ctx context.Context, query string) (Stmt, error)}

type Driver

驅(qū)動(dòng)程序是必須由數(shù)據(jù)庫(kù)驅(qū)動(dòng)程序?qū)崿F(xiàn)的接口。

type Driver interface {        // 打開返回到數(shù)據(jù)庫(kù)的新連接。        // 該名稱是一個(gè)驅(qū)動(dòng)程序特定格式的字符串。        //        // 打開可能會(huì)返回一個(gè)緩存的連接（之前一個(gè)        // 關(guān)閉），但這樣做是不必要的; sql包        // 維護(hù)一個(gè)空閑連接池以便有效地重用。        //        // 返回的連接僅由時(shí)間的一個(gè)goroutine使用        // 時(shí)間。        Open(name string) (Conn, error)}

type Execer

Execer 是一個(gè)可選接口，可由 Conn 實(shí)施。

如果 Conn 沒有實(shí)現(xiàn) Execer，那么 sql 包的 DB.Exec 將首先準(zhǔn)備一個(gè)查詢，執(zhí)行該語句，然后關(guān)閉該語句。

Exec 可能會(huì)返回 ErrSkip。

棄用：驅(qū)動(dòng)程序應(yīng)該實(shí)現(xiàn) ExecerContext （或另外）。

type Execer interface {        Exec(query string, args []Value) (Result, error)}

type ExecerContext

ExecerContext 是一個(gè)可以由 Conn 實(shí)現(xiàn)的可選接口。

如果 Conn 沒有實(shí)現(xiàn) ExecerContext，sql 包的 DB.Exec 將首先準(zhǔn)備一個(gè)查詢，執(zhí)行該語句，然后關(guān)閉該語句。

ExecerContext 可能會(huì)返回 ErrSkip。

ExecerContext 必須遵守上下文超時(shí)并在上下文被取消時(shí)返回。

type ExecerContext interface {        ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)}

type IsolationLevel

IsolationLeve l是存儲(chǔ)在 TxOptions 中的事務(wù)隔離級(jí)別。

這個(gè)類型應(yīng)該被認(rèn)為與 sql.IsolationLevel 以及在其上定義的任何值相同。

type IsolationLevel int

type NamedValue

NamedValue 包含值名稱和值。

type NamedValue struct {        // 如果名稱不是空的，它應(yīng)該用于參數(shù)標(biāo)識(shí)符和        // 而不是次序位置。        //        // 名稱不會(huì)有符號(hào)前綴。
        Name string        // 從一開始的參數(shù)序號(hào)位置始終設(shè)置。
        Ordinal int        // 值是參數(shù)值。
        Value Value}

type NamedValueChecker

NamedValueChecker 可以選擇由 Conn 或 Stmt 實(shí)現(xiàn)。它為驅(qū)動(dòng)程序提供了更多的控制來處理 Go 和數(shù)據(jù)庫(kù)類型，超出了允許的默認(rèn)值類型。

sql 包按以下順序檢查值檢查器，在第一個(gè)找到的匹配處停止：Stmt.NamedValueChecker，Conn.NamedValueChecker，Stmt.ColumnConverter，DefaultParameterConverter。

如果 CheckNamedValue 返回 ErrRemoveArgument，那么NamedValue 將不會(huì)包含在最終的查詢參數(shù)中。這可以用來將特殊選項(xiàng)傳遞給查詢本身。

如果返回 ErrSkip ，則列轉(zhuǎn)換器錯(cuò)誤檢查路徑用于參數(shù)。駕駛員可能希望在用盡特殊情況后返回 ErrSkip。

type NamedValueChecker interface {        // 在將參數(shù)傳遞給驅(qū)動(dòng)程序之前調(diào)用CheckNamedValue        // 并被調(diào)用來代替任何ColumnConverter。 CheckNamedValue必須輸入        // 驗(yàn)證和轉(zhuǎn)換適合驅(qū)動(dòng)程序。        CheckNamedValue(*NamedValue) error}

type NotNull

NotNull 是一種類型，它通過禁止 nil 值來實(shí)現(xiàn)ValueConverter，否則委托給另一個(gè) ValueConverter。

type NotNull struct {
        Converter ValueConverter}

func (NotNull) ConvertValue

func (n NotNull) ConvertValue(v interface{}) (Value, error)

type Null

Null 是一種通過允許 nil 值實(shí)現(xiàn) ValueConverter 的類型，但是可以委托給另一個(gè) ValueConverter。

type Null struct {
        Converter ValueConverter}

func (Null) ConvertValue

func (n Null) ConvertValue(v interface{}) (Value, error)

type Pinger

Pinger 是可由 Conn 實(shí)施的可選接口。

如果 Conn 沒有實(shí)現(xiàn) Pinger，則 sql 包的 DB.Ping 和DB.PingContext 將檢查是否至少有一個(gè)可用的 Conn。

如果 Conn.Ping 返回 ErrBadConn，則 DB.Ping 和DB.PingContext 將從池中移除 Conn。

type Pinger interface {        Ping(ctx context.Context) error}

type Queryer

Queryer 是一個(gè)可選的接口，可由 Conn 實(shí)施。

如果 Conn 沒有實(shí)現(xiàn) Queryer，那么 sql 包的 DB.Query 將首先準(zhǔn)備一個(gè)查詢，執(zhí)行該語句，然后關(guān)閉該語句。

Query 可能會(huì)返回 ErrSkip。

棄用：驅(qū)動(dòng)程序應(yīng)該實(shí)現(xiàn) QueryerContext（或另外）。

type Queryer interface {        Query(query string, args []Value) (Rows, error)}

type QueryerContext

QueryerContext 是一個(gè)可選接口，可由 Conn實(shí)施。

如果 Conn 沒有實(shí)現(xiàn) QueryerContext，則 sql 包的 DB.Query將首先準(zhǔn)備一個(gè)查詢，執(zhí)行該語句，然后關(guān)閉該語句。

QueryerContext 可能會(huì)返回 ErrSkip。

QueryerContext 必須遵守上下文超時(shí)并在上下文被取消時(shí)返回。

type QueryerContext interface {        QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)}

type Result

結(jié)果是查詢執(zhí)行的結(jié)果。

type Result interface {        // LastInsertId返回?cái)?shù)據(jù)庫(kù)的自動(dòng)生成的ID        // 例如，在將一個(gè)INSERT插入到具有主要表的表中        // 鍵（key）。        LastInsertId() (int64, error)        // RowsAffected返回受下列影響的行數(shù)        RowsAffected() (int64, error)}

type Rows

行是對(duì)已執(zhí)行的查詢結(jié)果的迭代器。

type Rows interface {        // 列將返回列的名稱。 以下的數(shù)量        // 結(jié)果的列從長(zhǎng)度推斷        // slice。 如果某個(gè)特定的列名未知，則為空        // 應(yīng)該為該條目返回字符串。        Columns() []string        // Close關(guān)閉行迭代器。        Close() error        // 接下來被調(diào)用來填充下一行數(shù)據(jù)        // 提供的切片(slice)。 提供的切片將是相同的        // 大小與Columns()一樣寬。        //        // 當(dāng)沒有更多行時(shí)，Next應(yīng)返回io.EOF。        Next(dest []Value) error}

type RowsAffected

RowsAffected 實(shí)現(xiàn)了一個(gè) INSERT 或 UPDATE 操作的 Result，該操作使多行變異。

type RowsAffected int64

func (RowsAffected) LastInsertId

func (RowsAffected) LastInsertId() (int64, error)

func (RowsAffected) RowsAffected

func (v RowsAffected) RowsAffected() (int64, error)

type RowsColumnTypeDatabaseTypeName

RowsColumnTypeDatabaseTypeName 可以通過行來實(shí)現(xiàn)。它應(yīng)該返回沒有長(zhǎng)度的數(shù)據(jù)庫(kù)系統(tǒng)類型名稱。類型名稱應(yīng)該是大寫的。返回類型的示例："VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT", "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML", "TIMESTAMP"。

type RowsColumnTypeDatabaseTypeName interface {
        Rows        ColumnTypeDatabaseTypeName(index int) string}

type RowsColumnTypeLength

RowsColumnTypeLength 可以通過行來實(shí)現(xiàn)。如果列是可變長(zhǎng)度類型，它應(yīng)該返回列類型的長(zhǎng)度。如果該列不是可變長(zhǎng)度類型，則應(yīng)返回 false。如果長(zhǎng)度不限于系統(tǒng)限制，它應(yīng)該返回math.MaxInt64。以下是各種類型返回值的示例：

TEXT          (math.MaxInt64, true)varchar(10)   (10, true)nvarchar(10)  (10, true)decimal       (0, false)int           (0, false)bytea(30)     (30, true)

type RowsColumnTypeLength interface {
        Rows        ColumnTypeLength(index int) (length int64, ok bool)}

type RowsColumnTypeNullable

RowsColumnTypeNullable 可以由 Rows實(shí)現(xiàn)。如果已知列可能為空，則可為空的值應(yīng)為 true ;如果列已知為不可空，則可為空值。如果列可空性未知，那么 ok 應(yīng)該是錯(cuò)誤的。

type RowsColumnTypeNullable interface {
        Rows        ColumnTypeNullable(index int) (nullable, ok bool)}

type RowsColumnTypePrecisionScale

RowsColumnTypePrecisionScale 可以通過行來實(shí)現(xiàn)。它應(yīng)該返回十進(jìn)制類型的精度和小數(shù)位數(shù)。如果不適用，確定應(yīng)該是錯(cuò)誤的。以下是各種類型返回值的示例：

decimal(38, 4)    (38, 4, true)int               (0, 0, false)decimal           (math.MaxInt64, math.MaxInt64, true)

type RowsColumnTypePrecisionScale interface {
        Rows        ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)}

type RowsColumnTypeScanType

RowsColumnTypeScanType 可以通過行來實(shí)現(xiàn)。它應(yīng)該返回可用于掃描類型的值類型。例如，數(shù)據(jù)庫(kù)列類型 “bigint” 應(yīng)該返回 “reflect.TypeOf(int64(0))”。

type RowsColumnTypeScanType interface {
        Rows        ColumnTypeScanType(index int) reflect.Type}

type RowsNextResultSet

RowsNextResultSet 通過提供一種方式來通知驅(qū)動(dòng)程序前進(jìn)到下一個(gè)結(jié)果集，從而擴(kuò)展了 Rows 接口。

type RowsNextResultSet interface {
        Rows        // HasNextResultSet在當(dāng)前結(jié)果集和結(jié)尾處被調(diào)用        // 報(bào)告當(dāng)前之后是否存在另一個(gè)結(jié)果集。        HasNextResultSet() bool        // NextResultSet將驅(qū)動(dòng)程序提前到下一個(gè)結(jié)果集        // 如果當(dāng)前結(jié)果集中有剩余的行。        //        // 當(dāng)沒有更多的結(jié)果集時(shí)，NextResultSet應(yīng)該返回io.EOF。        NextResultSet() error}

type Stmt

Stmt 是一個(gè)準(zhǔn)備好的聲明。它與 Conn 綁定，并且不被多個(gè)goroutine 同時(shí)使用。

type Stmt interface {        // Close關(guān)閉聲明。        //        // 從Go 1.1開始，Stmt在使用時(shí)不會(huì)關(guān)閉        // 任何查詢。        Close() error        // NumInput返回占位符參數(shù)的數(shù)量。        //        // 如果NumInput returns> = 0，則sql包將進(jìn)行完整性檢查        // 來自調(diào)用者的參數(shù)計(jì)數(shù)并將錯(cuò)誤返回給調(diào)用者        // 在語句的Exec或Query方法被調(diào)用之前。        //        // 如果驅(qū)動(dòng)程序不知道，NumInput也可能返回-1        // 其占位符的數(shù)量。 在那種情況下，sql包        // 將不會(huì)執(zhí)行檢查Exec或Query參數(shù)計(jì)數(shù)。        NumInput() int        // Exec執(zhí)行不返回行的查詢，例如        // INSERT或UPDATE。        //        // 棄用（Deprecated）：驅(qū)動(dòng)程序應(yīng)該實(shí)現(xiàn)StmtExecContext（或另外）。        // Query執(zhí)行可能返回行的查詢，例如一個(gè)        // SELECT。        //        // 棄用（Deprecated）：驅(qū)動(dòng)程序應(yīng)該實(shí)現(xiàn)StmtQueryContext（或另外）。        Query(args []Value) (Rows, error)}

• import "database/sql"

• 概述

• 索引

• 示例

• 子目錄

概述

Package sql 提供了一個(gè)圍繞SQL（或類似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