Blog.1 database.sql.driver

在事务操做中，要求事务的各个阶段都使用一个Conn链接。在链接被关闭以前，还须要执行rollback操做。

文章翻译了Go源码下database.sql.driver的接口规范，具体实现能够查看源码。

// 包driver定义了数据驱动要实现的接口，具体的实现会在包sql中用到。
//
// 更多仍是使用包sql中的代码
package driver

import (
    "context"
    "errors"
    "reflect"
)

// Value必须是一个驱动能够处理的值、NamedValueChecker接口可以处理的类型
// 或者下面这些类型的实例
//
//   int64
//   float64
//   bool
//   []byte
//   string
//   time.Time
//
// 若是驱动支持游标，返回值可能也实现Rows接口。举例，当用户
// 执行"select cursor(select * from my_table) from dual"。
// 若是返回的Rows被Close掉了，游标指向的数据也会被Close掉。
type Value interface{}

// NameValue 同时包括name和value
type NamedValue struct {
    // 若是Name不为空，它应该被用于参数标识符，而非序号位置。
    //
    // Name 没有符号前缀
    Name string

    // 参数从1开始的序号位置，而且老是被设置
    Ordinal int

    // Value是参数值
    Value Value
}

// Driver是一个必须被各个数据库driver实现的接口
//
// 数据库驱动能够实现DriverContext来访问上下文，而且只解析一次链接池的名称，
// 而非每一个链接都解析一次。
// 
type Driver interface {
    // Open返回数据库的一个新链接，参数name是驱动特定格式的字符串
    //
    // Open也能够返回一个缓存的链接（以前被close掉的），但这样
    // 作其实不必。sql包为了链接重复使用维护了一个空闲链接池
    //
    // 返回的链接一次只被一个goroutinue中使用
    Open(name string) (Conn, error)
}

// 若是Driver实现了DriverContext接口，那么sql.DB就会调用OpenConnector
// 来获取一个Connector，调用Connector的Conn方法来获取每一个须要的链接，
// 以此代替调用Drive的Open方法。这样容许drivers仅解析一次name，同时提供
// 对每一个链接上下文的访问
type DriverContext interface {
    // OpenConnector解析name的方式必须跟Driver.Open的方式保持一致
    OpenConnector(name string) (Connector, error)
}

// 一个Connector表示一个固定配置的driver，可以建立任意数量的等效Conn，
// 供多个goroutinue使用
//
// 一个Connector能被传递给sql.OpenDB方法，去容许驱动实现本身的sql.DB。
// 或者经过调用DriverContext的OpenConnector方法，来返回一个Connector，
// 这样容许驱动访问链接的上下文，避免频繁的解析驱动配置。
type Connector interface {
    // Connect返回一个数据库的链接
    // Connect可能返回一个以前缓存的链接（以前被close掉了），但这样去
    // 作实际上是不必的。sql包维护了一个高效重复使用的空闲链接池。
    //
    //
    // 被提供的context.Context参数仅仅被用于建立链接的目的
    //（看net.DialContext),不该该被存储或用于其余别的目的。
    //
    // 返回的链接一次只能被一个goroutine使用
    Connect(context.Context) (Conn, error)

    // Driver返回Connector的底层驱动，在sql.DB中，主要用于维护
    // 驱动的扩展性
    Driver() Driver
}

// ErrSkip 可能被一些可选接口的方法返回，用于在运行时标识该路径无效。
// 包sql应该继续去执行，就当类型没有实现这个接口同样。
// ErrSkip 只有在被明确说明后才会被支持
// 
var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")

// 当驱动给sql包标识一个driver.Conn处于坏的状态时，ErrBadConn应该被返回（
// 好比服务端已经关闭了这个链接），sql包已经使用一个新的链接进行重试
//
// 为了不重复操做，若是服务端可能已经完成操做的话，ErrBadConn不该该被返回。
// 即便服务端返回了一个错误，你也不该该返回ErrBadConn
var ErrBadConn = errors.New("driver: bad connection")

// Pinger是一个可选的接口，它可能会被Conn实现
// 
// 若是Conn没有实现Pinger接口，那么sql包的DB.Ping和DB.PingContext
// 将会执行检查，是否至少存在一个可用链接
//
// 若是Conn.Ping返回了ErrBadConn，DB.Ping 和 DB.PingContext将会从链接池中
// 将Conn溢出
type Pinger interface {
    Ping(ctx context.Context) error
}

// Execer 是一个能够被Conn实现的，可选的接口
//
// 若是Conn实现了ExecerContext或Excer，
// 包sql下的DB.Exec将首先prepare查询语句，执行而后关闭。
//
// Exec可能返回ErrSkip错误
//
// 弃用：Drivers应该实现ExecerContext接口来替代Execer
type Execer interface {
    Exec(query string, args []Value) (Result, error)
}

// ExecerContext是能够被Conn实现的、可选的接口
//
// 若是Conn并无实现ExecerContext接口，那sql包的DB.Exec将会向后调用Excer
// 若是Conn也没有实现Execer接口，
// DB.Exec将首先prepare查询，执行语句、而后关闭语句
//
// ExecerContext 可能返回 ErrSkip错误.
//
// ExecerContext必须认真对待context的超时，当context被取消时，须要返回。
// 
type ExecerContext interface {
    ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
}

// Queryer 是一个可选的接口，Conn可能会实现它。
//
// 若是Conn既没有实现QueryerContext，也没有实现Queryer
// 那么sql包的DB.Query首先会prepare一个查询语句，而后执行语句，关闭语句
//
// Query可能会返回 ErrSkip错误.
//
// 弃用：Drivers应该实现QueryerContext接口来替代Queryer
type Queryer interface {
    Query(query string, args []Value) (Rows, error)
}

// QueryerContext 是一个可选的接口，Conn可能会实现它
//
// 若是Conn没有实现QueryerContext，那么sql包在执行DB.Query会降级调用Queryer；
// 若是Conn也没有实现Queryer，DB.Query 首先会prepare一个查询语句，而后执行这个语句
// 而后再关闭它
//
// QueryerContext可能会返回 ErrSkip.
//
// QueryerContext必须认真对待context的超时，当context被cancel掉时，须要返回
type QueryerContext interface {
    QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
}

// Conn是一条数据库的链接，它不能在多个goroutine中同时使用。
//
// Conn被假定为是有状态的
type Conn interface {
    // Prepare返回一个准备好的语句，绑定到这个链接上
    Prepare(query string) (Stmt, error)

    // Close会使当前准备好的语句和事物失效，并可能中止它们执行，
    // 将这个链接标记为再也不使用
    //
    // 由于sql包维护了一个空闲链接池，仅当前有多余的空闲链接时，
    // 才会调用Close。对于驱动来讲，实现本身的链接缓存是没必要要的
    Close() error

    // Begin 启动并返回一个新的事务
    //
    // 弃用：驱动应该经过实现ConnBeginTx来替换Begin
    Begin() (Tx, error)
}

// ConnPrepareContext经过使用context，增强了Conn接口
type ConnPrepareContext interface {
    // context被用来对语句作预处理
    // 在语句自己中是不能够存储context的
    PrepareContext(ctx context.Context, query string) (Stmt, error)
}

// IsolationLevel在TxOptions类型中记录事物的隔离级别
//
// 这个类型应该认被为跟sql.IsolationLevel是一致的，以及定义这个类型的其余值。
// 
type IsolationLevel int

// TxOptions 设置事物的选项
//
// 这个类型应该被认为跟sql.TxOptions是一致的
type TxOptions struct {
    Isolation IsolationLevel
    ReadOnly  bool
}

// ConnBeginTx经过context和TxOptions提升了Conn接口
type ConnBeginTx interface {
    // BeginTx启动并返回一个新的事务
    // 若是context被用户取消了，sql包会在丢弃和关闭这个链接以前
    // 执行Tx.Rollback
    //
    // 函数必须检查opts.Isolation，肯定是否存在设置的额隔离级别。
    // 若是驱动不支持一个非默认的隔离级别和被设置的级别，或者
    // 存在一个非默认的隔离级别是不支持的，必须返回一个错误
    //
    // 函数也必须检查opts.ReadOnly，若是ReadOnly值为真，
    // 若是支持设置的话，则设置只读事务属性。若是不支持的话，返回error
    // 
    BeginTx(ctx context.Context, opts TxOptions) (Tx, error)
}

// Conn可能会实现SessionResetter接口，用于重置当前链接上的会话状态
// 并将当前链接标识为坏链接
type SessionResetter interface {
    // 当链接在链接池中时，调用ResetSession方法。该链接不会再承载任何查询操做
    // 直接方法返回
    //
    // 若是链接是坏的，方法应该返回driver.ErrBadConn错误，来阻止链接被放回到
    // 链接池。其余别的错误将会被丢弃
    ResetSession(ctx context.Context) error
}

// Result是查询执行的结果
type Result interface {
    // LastInsertId返回数据库自动生成的ID，好比，用主键插入表的操做
    LastInsertId() (int64, error)

    // RowsAffected返回查询影响的行数
    RowsAffected() (int64, error)
}

// Stmt是一个准备好的语句，它被绑定到一个Conn，且不能被多个goroutine并发
// 使用
type Stmt interface {
    // Close关闭这个语句
    //
    // 截止到Go 1.1，若是Stmt在被一些查询使用，Stmt将不会被关闭
    Close() error

    // NumInput返回占位符的个数
    //
    // 若是NumInput返回值大于等于0，sql包会明智的检查调用者的参数个数，
    // 在Exec或Query被调用以前，返回错误给调用者。
    //
    // 若是驱动不知道占位符的个数，NumInput可能会返回-1。在这种状况下，
    // sql包将不会检查Exec和Query的参数个数
    NumInput() int

    // Exec执行一个不返回数据行的查询，好比INSERT或UPDATE
    //
    // 弃用：驱动应实现StmtExecContext来替代
    Exec(args []Value) (Result, error)

    // Query执行一个返回数据行的查询，好比SELECT
    //
    // 弃用：驱动应实现StmtQueryContext来替代
    Query(args []Value) (Rows, error)
}

// StmtExecContext升级了Stmt接口，它提供了一个有context的Exec，
type StmtExecContext interface {
    // ExecContext执行一个不返回数据行的查询，好比INSERT或UPDATE
    //
    // ExecContext必须遵照context超时，当context被取消时，函数须要返回
    ExecContext(ctx context.Context, args []NamedValue) (Result, error)
}

// StmtQueryContext升级了Stmt接口，它提供了一个有context的Query
type StmtQueryContext interface {
    // QueryContext执行一个返回数据行的查询，好比SELECT
    //
    // ExecContext必须遵照context超时，当context被取消时，函数须要返回
    QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
}

// ErrRemoveArgument可能被NamedValueChecker返回，用来指示sql包不要
// 给驱动的query接口传递这个参数。
// 当接收到不是查询参数的特定属性或结构时，返回该错误
var ErrRemoveArgument = errors.New("driver: remove argument from query")

// Conn或Stmt可选择是否要实现NamedValueChecker接口。接口提供给驱动
// 更多的控制，去处理超出Go和数据库容许的默认值类型。
//
// 对于值的检查对象，sql包按以下顺序进行检查。当第一次发现匹配时中止：
// Stmt.NamedValueChecker, Conn.NamedValueChecker, Stmt.ColumnConverter,
// DefaultParameterConverter.
//
// 若是CheckNamedValue返回ErrRemoveArgument错误，那么这个NamedValue将不会
// 被包含在最终的查询参数中。这可能会被用于给查询传递特殊的选项。
//
// 若是ErrSkip错误被返回，则使用列转换器错误检查路径做为参数。
// 驱动可能但愿在耗尽本身特殊case后返回ErrSkip
type NamedValueChecker interface {
    // 在传递参数给驱动以前，CheckNamedValue会被调用。
    // 在任何ColumnConverter的地方也会调用CheckNamedValue。
    // CheckNamedValue必须根据驱动的须要作类型校验和转换
    CheckNamedValue(*NamedValue) error
}

// 若是语句知道本身列的类型，而且可以从任何类型转换为驱动的Value，
// 那么Stmt 能够选择性的实现ColumnConverter
// 
// 弃用：驱动应实现NamedValueChecker
type ColumnConverter interface {
    // 根据提供的列序号，ColumnConverter返回一个 ValueConverter。
    // 若是该列是未知的或者不须要被特殊处理，方法返回DefaultValueConverter
    ColumnConverter(idx int) ValueConverter
}

// Rows是一个查询结果的迭代器
type Rows interface {
    // Columns返回列的名字集，它的个数是从slice的长度中推断出来的。
    // 若是不知道特定的列名，应该为该条目返回一个空的字符串
    Columns() []string

    // 关闭行迭代器
    Close() error

    // Next用于把数据集中的下一行填入提供的slice中。该slice的
    // 长度应该跟Columns()的长度一致
    //
    // 当没有数据行时，Next应该返回io.EOF
    // 
    // dest不该被声明在Next以外(应该做为Next的一个成员变量)
    // 关闭Rows时应特别注意，不要修改dest中缓冲区的值
    Next(dest []Value) error
}

// RowsNextResultSet扩展了Rows接口，它提供了一个方式，让驱动向前移动
// 到下一个结果集
type RowsNextResultSet interface {
    Rows

    // 在当前结果集的末尾调用HasNextResultSet，报告当前结果集以后是否还存在
    // 别的结果集
    HasNextResultSet() bool

    // NextResultSet向前移动驱动到下一个结果集，即便当前结果集
    // 仍然存在剩余的数据行
    //
    // 当再也不有数据集时，NextResultSet应该返回io.EOF
    NextResultSet() error
}

// RowsColumnTypeScanType能够经过Rows实现，它应该返回可用于扫描的数据类型。
// 好比，数据库的列类型`bigint`应该返回"reflect.TypeOf(int64(0))".
type RowsColumnTypeScanType interface {
    Rows
    ColumnTypeScanType(index int) reflect.Type
}

// RowsColumnTypeDatabaseTypeName能够经过Rows实现。它应该返回不包括字段长度的数据库类型，
// 类型名应该全大写。诸如："VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT",
// "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML",
// "TIMESTAMP".
type RowsColumnTypeDatabaseTypeName interface {
    Rows
    ColumnTypeDatabaseTypeName(index int) string
}

// RowsColumnTypeLength能够经过Rows实现，若是列是可变长度的类型，它应该返回
// 类型的长度。若是列是不可变长度的类型，ok返回false。
// 若是类型长度只受系统限制，则应该返回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)
}

// RowsColumnTypeNullable能够经过Rows实现。若是指定的列能够为空，则nullable
// 返回true。相反，若是列不能为空，nullable应该返回false。
// 若是不知道该列是否能够为空，ok应该返回false
type RowsColumnTypeNullable interface {
    Rows
    ColumnTypeNullable(index int) (nullable, ok bool)
}

// RowsColumnTypePrecisionScale能够被Rows实现，对于decimal类型，它应该返回
// 精度和小数点右边的范围。若是类型不适用，ok应返回false
// 下面是不一样类型的返回值示例：
//   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)
}

// Tx是一个事务
type Tx interface {
    Commit() error
    Rollback() error
}

// RowsAffected实现了INSERT或UPDATE操做的结果
// 表示被影响的行数
type RowsAffected int64

var _ Result = RowsAffected(0)

func (RowsAffected) LastInsertId() (int64, error) {
    return 0, errors.New("LastInsertId is not supported by this driver")
}

func (v RowsAffected) RowsAffected() (int64, error) {
    return int64(v), nil
}

// ResultNoRows是一个预约义的结果，在一个DDL操做(好比CREATE TABLE)执行成功
// 时返回。调用该类型的LastInsertId和LastInsertId方法会返回错误
var ResultNoRows noRows

type noRows struct{}

var _ Result = noRows{}

func (noRows) LastInsertId() (int64, error) {
    return 0, errors.New("no LastInsertId available after DDL statement")
}

func (noRows) RowsAffected() (int64, error) {
    return 0, errors.New("no RowsAffected available after DDL statement")
}