标准库 database/sql/driver 翻译

package driver

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

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

=================================================================================

Value 是 drivers 必须能够操作的值。

它要么是 nil —— 一个被数据库 driver 的 NamedValueChecker 接口操作的类型,或者以下类型的实例:

  • int64

  • float64

  • bool

  • []byte

  • string

  • time.Time

    type Value interface{}

NamedValue 装载了 value name 和 value。

type NamedValue struct {
    Name        string      // 如果 Name 字段不是空的,它应该使用关键字参数方式赋值,而不是位置参数方式。
    Ordinal     int     // 位置参数方式赋值。
    Value       value       // 关键字参数方式赋值。
}

Driver 是一个database dirver 必须实现的接口。

Database drivers 应该实现 DriverContext ,用于访问 contexts 和解析一次连接池的名字,而不是每个连接解析一次。

type Driver interface {
    Open(name string) (Conn, error)     // Open 返回一个新的到数据库的连接。name 参数,是一个 database 特定格式的字符串。
}                       // Open 可以返回一个缓存的连接,但是这样做没有必要;该 sql 包维持着一个空闲的连接池以便重用。

如果一个 driver 实现了 DriverContext,那么 sql.DB 将能够调用 OpenConnector 来获得一个 连接器,并调用 连接器的 Conn 方法来获得每个所需的连接,而不是使用 Open 方法。这使得 driver 可以提供对连接的 context 的访问。

type DriverContext interface {
    OpenConnector(name string) (Connector, error)
}

Connector,连接器,代表了一个固定配置的连接器,可以创建任意数量的 Conns (对象)来被多个 goroutine 使用。

一个连接器能够被传给 sql.OpenDB,以允许 drivers 实现他们自己的 sql.DB 构造器,或者被 DriverContext 的 OpenConnector 方法返回,并允许 driver 访问 context,避免重复解析配置。

type Connector interface {
    Connect(context.Context) (Conn, error)  // Connect 返回一个到数据库的连接。
    Driver() Driver             // Driver 返回 Connector 底层的驱动,用于和 sql.DB 上的 Driver 方法兼容。
}

ErrSkip 可以被一些可选的方法返回,用以指示 fast path 在运行时中不可用,并且该 sql 包应该延续,因为该可选参数没有实现。ErrSkip 仅仅被显式说明的地方支持。

var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")

ErrBadConn 应该被 driver 用于表示一个 driver.Conn 处于坏的状态时返回给 sql 包,而 sql 包应该尝试新的连接。

var ErrBadConn = errors.New("driver: bad connection")

Pinger 是一个可选的接口,被 Conn 实现。如果一个 Conn 没有实现 Pinger,sql 包的 DB.Ping 和 DB.PingContext 将检测是否有至少一个 Conn 可用。

Conn.Ping 返回 ErrBadConn,DB.Ping 和 DB.PingContext 将会从连接池中删除 Conn。

type Pinger interface {
    Ping(ctx context.Context) error
}

Execer 是一个可选接口,被 Conn 实现。如果 Conn 既没有实现 ExecerContext 和 Execer,那么 sql 包的 DB.Exec 将首先准备一个查询,执行该 statement,并关闭该 statement。

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

ExecerContext 是一个可选接口,被 Conn 实现。如果一个 Conn 没有实现 ExecerContext,该 sql 包的 DB.Exec 将退化为 Execer。

type ExecerContext interface {
    ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
}

Queryer 是一个可选接口,被 Conn 实现。

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

type QueryerContext interface {
    QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
}

Conn 是一个到 database 的连接。它不可以被多个 goroutine 并发使用。Conn 是有状态的。

type Conn interface {
    Prepare(query string) (Stmt, error)     // Prepare 返回一个准备好的 statement,绑定到 connection。
    Close() error                   // Close 使当前的 statement 无效,使当前的事务停止,并标记该连接不再使用。
    Begin() (Tx, error)             // Begin 开始并返回一个事务。
}

ConnPrepareContext 改良了 Conn 接口。

type ConnPrepareContext interface {
    PrepareContext(ctx context.Context, query string) (Stmt, error)     // Context 用于 preparation,而非 statement。
}

IsolationLevel 是一个在 TxOptions 中存储的事务隔离级别。

该类型,连同值,应该被认为和 sql.IsolationLevel 是一样的。

type IsolationLevel int

TxOptions 保存着 transaction 的参数。

type TxOptions struct {
    Isolation   IsolationLevel
    ReadOnly    bool
}

ConnBeginTx 通过 context 和 TxOptions 增强了 Conn 接口。

type ConnBeginTx interface {
    BeginTx(ctx context.Context, opts TxOptions) (Tx, error)    // 如果 context 被取消,那么用户的 sql 包将在丢弃和关闭连接前调用 Tx.Rollback。这将必须检查 opts.Isolation 来决定是否设置了隔离级别。如果 driver 不支持 非默认级别,并且设置了一个级别,或者是不支持默认级别,那么将返回错误。
}

SessionResetter 可以被 Conn 实现,以允许 drivers 来重置 session 状态,并发送一个 bad connection 信号。

type SessionResetter interface {
    ResetSession(ctx context.Context) error     // 当一个连接在连接池中时,ResetSession 将被调用。在该方法被调用之前,没有请求被运行。
}

Result 是 查询执行的结果。

type Result interface {
    LastInsertId() (int64, error)           // LastInsertId 返回 database 自增 ID,比如是在 insert into a table 之后。
    RowsAffected() (int64, error)           // RowsAffected 返回 生效的 rows 数量。
}

Stmt 是一个准备好的 statement。 它和一个 Conn 绑定,而不被多重 goroutine 使用。

type Stmt interface {
    Close() error               // 关闭 Stmt
    NumInput() int              // NumInput 返回占位符参数的数量。如果 NumInput 返回大于等于0,该 sql 包将检查参数个数。
    Exec(args []Value) (Result, error)  // Exec 执行不返回行数的查询,比如 insert 和 update。
    Query(args []Value) (Rows, error)   // Query 执行返回行数的查询,比如 select。
}

StmtExecContext 增强 Stmt 接口通过 ExecContext。

type StmtExecContext interface {
    ExecContext(ctx context.Context, args []NamedValue) (Result, error)
}

type StmtQueryContext interface {
    QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
}

NamedValueChecker 可以被 Conn 或 Stmt 选择实现。它提供给 drivers 在默认允许的值类型以外,更多的控制以操作 go 和 database 类型。

sql 包通过以下的顺序检测值,从以下的顺序找到就停止:Stmt.NamedValueChecker, Conn.NamedValueChecker, Stmt.ColumnConventer, DefaultParameterConventer。

如果 CheckNamedValue 返回 ErrRemoveArgument,该 NamedValue 将被包含在最终的查询参数中。这将可能用于传递特定的参数到请求。

如果 ErrSkip 被列转换器返回,那么 error 检测路径将被用于参数。Drivers 可能希望返回 ErrSkip。

type NamedValueChecker interface {
    CheckNameValue(*NamedValue) error   // 在参数传递给 driver 之前,CheckNamedValue 方法被调用;并且代替 ColumnConventer。CheckNamedValue 必须做类型验证,并转换为 driver 适用的类型。
}

ColumnConventer 可以被 Stmt 选择实现,如果 statement 意识到它自己的 column 类型,并从到一个驱动值的类型转换。

type ColumnConventer interface {
    ColumnConventer(idx int) ValueConventer     // ColumnConventer 返回一个 ValueConventer,用于提供列序号。如果指定列的类型未知,或者不应该被操作,DefaultValueConventer 能够被返回。
}

Rows 是一个迭代器,构建于可执行的请求结果。

type Rows interface {
    Columns() []string      // Columns 返回 列名。结果中的列数,是从结果切片中推断出来的。如果某个列名未知,那么会返回一个空字符串。
    Close() error           // 关闭该 行迭代器。
    Next(dest []Value) error    // Next 用于把下一行数据转移到 slice。提供的 slice 应该和 Columns 方法提供的一样宽。如果没有更多的行,那么 Next 应该返回 io.EOF。dest 参数不要写在 Next 方法之外。注意,在关闭 Rows 以后,就不能修改 dest 中装载的数据了。
}

RowsNextResultSet 扩展 Rows 接口,通过把 发送到 driver 的信号发送给 next result set。

type RowsNextResultSet interface {
    Rows
    HasNextResultSet() bool     // HasNextResultSet 在当前结果集的最后被调用,报告是否还有下一结果集
    NextResultSet() error
}

RowsColumnTypeScanType 可以被 Rows 实现。它应该返回值类型能够被用于把类型扫描进入。例如,database column 类型 "bigint" 应该被返回 "reflect.TypeOf(int64(0))"。

type RowsColumnTypeScanType interface {
    Rows
    ColumnTypeScanType(index int) reflect.Type
}

RowsColumnTypeDatabaseTypeName 可以被 Rows 实现。它应该返回该数据库系统中不带长度的类型名称。类型名称应该小写。

type RowsColumnDatabaseTypeName interface {
    Rows
    ColumnTypeDatabaseTypeName(index int) string
}

RowsColumnTypeLength 可以被 Rows 实现。如果是变长类型,它应该返回 column type 的长度。如果不是变长类型,它应该返回 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。

type RowsColumnTypeNullable interface {
    Rows
    ColumnTypeNullable(index int) (nullable, ok bool)
}

RowsColumnTypePrecisionScale 可以被 Rows 实现。它应该返回 decimal 的精度和量级。如果不可应用,ok 参数应该为 false。以下是返回值的例子:

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("no LastInsertId available")
}

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

ResultNoRows 是一个 当 DDL 命令成功时,drivers 预定义的返回结果。当 LastInsertId 和 RowsAffected 同时存在时,返回错误。

var ResultNotRows 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")
}

你可能感兴趣的:(标准库 database/sql/driver 翻译)