package driver

import "database/sql/driver"

driver包定义了应被数据库驱动实现的接口,这些接口会被sql包使用。

绝大多数代码应使用sql包。

Index

返回首页


  • Variables
  • type Value
  • type Valuer
  • func IsValue(v interface{}) bool
  • func IsScanValue(v interface{}) bool
  • type ValueConverter
  • type ColumnConverter
  • type NotNull
  • type Null
  • type Driver
  • type Conn
  • type Execer
  • type Queryer
  • type Stmt
  • type Tx
  • type Result
  • type RowsAffected
  • type 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

    type Value interface{}

    Value是驱动必须能处理的值。它要么是nil,要么是如下类型的实例:

    int64
    float64
    bool
    []byte
    string   [*] Rows.Next不会返回该类型值
    time.Time

    type Valuer

    type Valuer interface {
        // Value返回一个驱动支持的Value类型值
        Value() (Value, error)
    }

    Valuer是提供Value方法的接口。实现了Valuer接口的类型可以将自身转换为驱动支持的Value类型值。

    func IsValue

    func IsValue(v interface{}) bool

    IsValue报告v是否是合法的Value类型参数。和IsScanValue不同,IsValue接受字符串类型。

    func IsScanValue

    func IsScanValue(v interface{}) bool

    IsScanValue报告v是否是合法的Value扫描类型参数。和IsValue不同,IsScanValue不接受字符串类型。

    type ValueConverter

    type ValueConverter interface {
        // ConvertValue将一个值转换为驱动支持的Value类型
        ConvertValue(v interface{}) (Value, error)
    }

    ValueConverter接口提供了ConvertValue方法。

    driver包提供了各种ValueConverter接口的实现,以保证不同驱动之间的实现和转换的一致性。ValueConverter接口有如下用途:

    * 转换sql包提供的Value类型值到数据库指定列的类型,并保证它的匹配,
      例如保证某个int64值满足一个表的uint16列。
    
    * 转换数据库提供的值到驱动的Value类型。
    
    * 在扫描时被sql包用于将驱动的Value类型转换为用户的类型。

    type ColumnConverter

    type ColumnConverter interface {
        // ColumnConverter返回指定列的ValueConverter
        // 如果该列未指定类型,或不应特殊处理,应返回DefaultValueConverter
        ColumnConverter(idx int) ValueConverter
    }

    如果Stmt有自己的列类型,可以实现ColumnConverter接口,返回值可以将任意类型转换为驱动的Value类型。

    type NotNull

    type NotNull struct {
        Converter ValueConverter
    }

    NotNull实现了ValueConverter接口,不允许nil值,否则会将值交给Converter字段处理。

    func (NotNull) ConvertValue

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

    type Null

    type Null struct {
        Converter ValueConverter
    }

    Null实现了ValueConverter接口,允许nil值,否则会将值交给Converter字段处理。

    func (Null) ConvertValue

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

    type Driver

    type Driver interface {
        // Open返回一个新的与数据库的连接,参数name的格式是驱动特定的。
        //
        // Open可能返回一个缓存的连接(之前关闭的连接),但这么做是不必要的;
        // sql包会维护闲置连接池以便有效的重用连接。
        //
        // 返回的连接同一时间只会被一个go程使用。
        Open(name string) (Conn, error)
    }

    Driver接口必须被数据库驱动实现。

    type Conn

    type Conn interface {
        // Prepare返回一个准备好的、绑定到该连接的状态。
        Prepare(query string) (Stmt, error)
    
        // Close作废并停止任何现在准备好的状态和事务,将该连接标注为不再使用。
        //
        // 因为sql包维护着一个连接池,只有当闲置连接过剩时才会调用Close方法,
        // 驱动的实现中不需要添加自己的连接缓存池。
        Close() error
    
        // Begin开始并返回一个新的事务。
        Begin() (Tx, error)
    }

    Conn是与数据库的连接。该连接不会被多线程并行使用。连接被假定为具有状态的。

    type Execer

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

    Execer是一个可选的、可能被Conn接口实现的接口。

    如果一个Conn未实现Execer接口,sql包的DB.Exec会首先准备一个查询,执行状态,然后关闭状态。Exec可能会返回ErrSkip。

    type Queryer

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

    Queryer是一个可选的、可能被Conn接口实现的接口。

    如果一个Conn未实现Queryer接口,sql包的DB.Query会首先准备一个查询,执行状态,然后关闭状态。Query可能会返回ErrSkip。

    type Stmt

    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

    type Tx interface {
        Commit() error
        Rollback() error
    }

    Tx是一次事务。

    type Result

    type Result interface {
        // LastInsertId返回insert等命令后数据库自动生成的ID
        LastInsertId() (int64, error)
    
        // RowsAffected返回被查询影响的行数
        RowsAffected() (int64, error)
    }

    Result是查询执行的结果。

    type RowsAffected

    type RowsAffected int64

    RowsAffected实现了Result接口,用于insert或update操作,这些操作会修改零到多行数据。

    func (RowsAffected) LastInsertId

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

    func (RowsAffected) RowsAffected

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

    type Rows

    type Rows interface {
        // Columns返回各列的名称,列的数量可以从切片长度确定。
        // 如果某个列的名称未知,对应的条目应为空字符串。
        Columns() []string
    
        // Close关闭Rows。
        Close() error
    
        // 调用Next方法以将下一行数据填充进提供的切片中。
        // 提供的切片必须和Columns返回的切片长度相同。
        //
        // 切片dest可能被填充同一种驱动Value类型,但字符串除外。
        // 所有string值都必须转换为[]byte。
        //
        // 当没有更多行时,Next应返回io.EOF。
        Next(dest []Value) error
    }

    Rows是执行查询得到的结果的迭代器。