Go 语言

Go 语言教程 Go 语言环境安装 Go 语言结构 Go 语言基础语法 Go 语言数据类型 Go 语言变量 Go 语言常量 Go 语言运算符 Go 语言条件语句 Go 语言 if 语句 Go 语言 if...else 语句 Go 语言 if 语句嵌套 Go 语言 switch 语句 Go 语言 select 语句 Go 语言循环语句 Go 语言 for 循环 Go 语言循环嵌套 Go 语言 break 语句 Go 语言 continue 语句 Go 语言 goto 语句 Go 语言函数 Go 语言函数值传递值 Go 语言函数引用传递值 Go 语言函数作为值 Go 语言函数闭包 Go 语言函数方法 Go 语言变量作用域 Go 语言数组 Go 语言多维数组 Go 语言向函数传递数组 Go 语言指针 Go 语言指针数组 Go 语言指向指针的指针 Go 语言指针作为函数参数 Go 语言结构体 Go 语言切片(Slice) Go 语言范围(Range) Go 语言Map(集合) Go 语言递归函数 Go 语言类型转换 Go 语言接口 Go 错误处理 Go 语言开发工具Go 语言标准库

Go 语言标准库


package driver

import "database/sql/driver"

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

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

Go语言标准库 >>


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