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是执行查询得到的结果的迭代器。