package driver · Go 標準庫中文參考

# package driver `import "database/sql/driver"` driver包定義了應被數據庫驅動實現的接口，這些接口會被sql包使用。絕大多數代碼應使用sql包。 ## Index * [Variables](#pkg-variables) * [type Value](#Value) * [type Valuer](#Valuer) * [func IsValue(v interface{}) bool](#IsValue) * [func IsScanValue(v interface{}) bool](#IsScanValue) * [type ValueConverter](#ValueConverter) * [type ColumnConverter](#ColumnConverter) * [type NotNull](#NotNull) * [func (n NotNull) ConvertValue(v interface{}) (Value, error)](#NotNull.ConvertValue) * [type Null](#Null) * [func (n Null) ConvertValue(v interface{}) (Value, error)](#Null.ConvertValue) * [type Driver](#Driver) * [type Conn](#Conn) * [type Execer](#Execer) * [type Queryer](#Queryer) * [type Stmt](#Stmt) * [type Tx](#Tx) * [type Result](#Result) * [type RowsAffected](#RowsAffected) * [func (RowsAffected) LastInsertId() (int64, error)](#RowsAffected.LastInsertId) * [func (v RowsAffected) RowsAffected() (int64, error)](#RowsAffected.RowsAffected) * [type Rows](#Rows) ## Variables ``` var Bool boolType ``` Bool是ValueConverter接口值，用于將輸入的值轉換為布爾類型。轉換規則如下： ``` - 布爾類型：不做修改 - 整數類型： 1 為真 0 為假其余整數會導致錯誤 - 字符串和[]byte：與strconv.ParseBool的規則相同 - 所有其他類型都會導致錯誤 ``` ``` var Int32 int32Type ``` Int32是一個ValueConverter接口值，用于將值轉換為int64類型，會尊重int32類型的限制。 ``` var String stringType ``` String是一個ValueConverter接口值，用于將值轉換為字符串。如果值v是字符串或者[]byte類型，不會做修改，如果值v是其它類型，會轉換為fmt.Sprintf("%v", v)。 ``` var DefaultParameterConverter defaultConverter ``` DefaultParameterConverter是ValueConverter接口的默認實現，當一個Stmt沒有實現ColumnConverter時，就會使用它。如果值value滿足函數IsValue(value)為真，DefaultParameterConverter直接返回 value。否則，整數類型會被轉換為int64，浮點數轉換為float64，字符串轉換為[]byte。其它類型會導致錯誤。 ``` var ResultNoRows noRows ``` ResultNoRows是預定義的Result類型值，用于當一個DDL命令（如create table）成功時被驅動返回。它的LastInsertId和RowsAffected方法都返回錯誤。 ``` var ErrBadConn = errors.New("driver: bad connection") ``` ErrBadConn應被驅動返回，以通知sql包一個driver.Conn處于損壞狀態（如服務端之前關閉了連接），sql包會重啟一個新的連接。為了避免重復的操作，如果數據庫服務端執行了操作，就不應返回ErrBadConn。即使服務端返回了一個錯誤。 ``` var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented") ``` ErrSkip可能會被某些可選接口的方法返回，用于在運行時表明快速方法不可用，sql包應像未實現該接口的情況一樣執行。ErrSkip只有文檔顯式說明的地方才支持。 ## type [Value](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#22 "View Source") ``` type Value interface{} ``` Value是驅動必須能處理的值。它要么是nil，要么是如下類型的實例： ``` int64 float64 bool []byte string [*] Rows.Next不會返回該類型值 time.Time ``` ## type [Valuer](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#39 "View Source") ``` type Valuer interface { // Value返回一個驅動支持的Value類型值 Value() (Value, error) } ``` Valuer是提供Value方法的接口。實現了Valuer接口的類型可以將自身轉換為驅動支持的Value類型值。 ## func [IsValue](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#176 "View Source") ``` func IsValue(v interface{}) bool ``` IsValue報告v是否是合法的Value類型參數。和IsScanValue不同，IsValue接受字符串類型。 ## func [IsScanValue](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#188 "View Source") ``` func IsScanValue(v interface{}) bool ``` IsScanValue報告v是否是合法的Value掃描類型參數。和IsValue不同，IsScanValue不接受字符串類型。 ## type [ValueConverter](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#30 "View Source") ``` type ValueConverter interface { // ConvertValue將一個值轉換為驅動支持的Value類型 ConvertValue(v interface{}) (Value, error) } ``` ValueConverter接口提供了ConvertValue方法。 driver包提供了各種ValueConverter接口的實現，以保證不同驅動之間的實現和轉換的一致性。ValueConverter接口有如下用途： ``` * 轉換sql包提供的Value類型值到數據庫指定列的類型，并保證它的匹配，例如保證某個int64值滿足一個表的uint16列。 * 轉換數據庫提供的值到驅動的Value類型。 * 在掃描時被sql包用于將驅動的Value類型轉換為用戶的類型。 ``` ## type [ColumnConverter](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#145 "View Source") ``` type ColumnConverter interface { // ColumnConverter返回指定列的ValueConverter // 如果該列未指定類型，或不應特殊處理，應返回DefaultValueConverter ColumnConverter(idx int) ValueConverter } ``` 如果Stmt有自己的列類型，可以實現ColumnConverter接口，返回值可以將任意類型轉換為驅動的Value類型。 ## type [NotNull](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#163 "View Source") ``` type NotNull struct { Converter ValueConverter } ``` NotNull實現了ValueConverter接口，不允許nil值，否則會將值交給Converter字段處理。 ### func (NotNull) [ConvertValue](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#167 "View Source") ``` func (n NotNull) ConvertValue(v interface{}) (Value, error) ``` ## type [Null](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#150 "View Source") ``` type Null struct { Converter ValueConverter } ``` Null實現了ValueConverter接口，允許nil值，否則會將值交給Converter字段處理。 ### func (Null) [ConvertValue](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#154 "View Source") ``` func (n Null) ConvertValue(v interface{}) (Value, error) ``` ## type [Driver](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#26 "View Source") ``` type Driver interface { // Open返回一個新的與數據庫的連接，參數name的格式是驅動特定的。 // // Open可能返回一個緩存的連接（之前關閉的連接），但這么做是不必要的； // sql包會維護閑置連接池以便有效的重用連接。 // // 返回的連接同一時間只會被一個go程使用。 Open(name string) (Conn, error) } ``` Driver接口必須被數據庫驅動實現。 ## type [Conn](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#83 "View Source") ``` type Conn interface { // Prepare返回一個準備好的、綁定到該連接的狀態。 Prepare(query string) (Stmt, error) // Close作廢并停止任何現在準備好的狀態和事務，將該連接標注為不再使用。 // // 因為sql包維護著一個連接池，只有當閑置連接過剩時才會調用Close方法， // 驅動的實現中不需要添加自己的連接緩存池。 Close() error // Begin開始并返回一個新的事務。 Begin() (Tx, error) } ``` Conn是與數據庫的連接。該連接不會被多線程并行使用。連接被假定為具有狀態的。 ## type [Execer](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#64 "View Source") ``` type Execer interface { Exec(query string, args []Value) (Result, error) } ``` Execer是一個可選的、可能被Conn接口實現的接口。如果一個Conn未實現Execer接口，sql包的DB.Exec會首先準備一個查詢，執行狀態，然后關閉狀態。Exec可能會返回ErrSkip。 ## type [Queryer](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#75 "View Source") ``` type Queryer interface { Query(query string, args []Value) (Rows, error) } ``` Queryer是一個可選的、可能被Conn接口實現的接口。如果一個Conn未實現Queryer接口，sql包的DB.Query會首先準備一個查詢，執行狀態，然后關閉狀態。Query可能會返回ErrSkip。 ## type [Stmt](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#115 "View Source") ``` type Stmt interface { // Close關閉Stmt。 // // 和Go1.1一樣，如果Stmt被任何查詢使用中的話，將不會被關閉。 Close() error // NumInput返回占位參數的個數。 // // 如果NumInput返回值 >= 0，sql包會提前檢查調用者提供的參數個數， // 并且會在調用Exec或Query方法前返回數目不對的錯誤。 // // NumInput可以返回-1，如果驅動占位參數的數量。 // 此時sql包不會提前檢查參數個數。 NumInput() int // Exec執行查詢，而不會返回結果，如insert或update。 Exec(args []Value) (Result, error) // Query執行查詢并返回結果，如select。 Query(args []Value) (Rows, error) } ``` Stmt是準備好的狀態。它會綁定到一個連接，不應被多go程同時使用。 ## type [Tx](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#177 "View Source") ``` type Tx interface { Commit() error Rollback() error } ``` Tx是一次事務。 ## type [Result](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#102 "View Source") ``` type Result interface { // LastInsertId返回insert等命令后數據庫自動生成的ID LastInsertId() (int64, error) // RowsAffected返回被查詢影響的行數 RowsAffected() (int64, error) } ``` Result是查詢執行的結果。 ## type [RowsAffected](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#184 "View Source") ``` type RowsAffected int64 ``` RowsAffected實現了Result接口，用于insert或update操作，這些操作會修改零到多行數據。 ### func (RowsAffected) [LastInsertId](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#188 "View Source") ``` func (RowsAffected) LastInsertId() (int64, error) ``` ### func (RowsAffected) [RowsAffected](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#192 "View Source") ``` func (v RowsAffected) RowsAffected() (int64, error) ``` ## type [Rows](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#154 "View Source") ``` type Rows interface { // Columns返回各列的名稱，列的數量可以從切片長度確定。 // 如果某個列的名稱未知，對應的條目應為空字符串。 Columns() []string // Close關閉Rows。 Close() error // 調用Next方法以將下一行數據填充進提供的切片中。 // 提供的切片必須和Columns返回的切片長度相同。 // // 切片dest可能被填充同一種驅動Value類型，但字符串除外。 // 所有string值都必須轉換為[]byte。 // // 當沒有更多行時，Next應返回io.EOF。 Next(dest []Value) error } ``` Rows是執行查詢得到的結果的迭代器。