数据库/sql/driver | database/sql/driver

• import "database/sql/driver"

• 概述

• 索引

概述

软件包驱动程序定义由 sql 包使用的数据库驱动程序实现的接口。

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

索引

• 变量（Variables）

• func IsScanValue(v interface{}) bool

• func IsValue(v interface{}) bool

• type ColumnConverter

• type Conn

• type ConnBeginTx

• type ConnPrepareContext

• type Driver

• type Execer

• type ExecerContext

• type IsolationLevel

• type NamedValue

• type NamedValueChecker

• type NotNull

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

• type Null

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

• type Pinger

• type Queryer

• type QueryerContext

• type Result

• type Rows

• type RowsAffected

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

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

• type RowsColumnTypeDatabaseTypeName

• type RowsColumnTypeLength

• type RowsColumnTypeNullable

• type RowsColumnTypePrecisionScale

• type RowsColumnTypeScanType

• type RowsNextResultSet

• type Stmt

• type StmtExecContext

• type StmtQueryContext

• type Tx

• type TxOptions

• type Value

• type ValueConverter

• type Valuer

包文件

driver.go types.go

变量

Bool 是一个将输入值转换为布尔值的 ValueConverter。

转换规则是：

 - 布尔值不变
- 对于整数类型，
     1是真的
     0是假的，
     其他整数是一个错误
- 对于字符串和[]字节，与strconv.ParseBool相同的规则
- 所有其他类型都是错误的

var Bool boolType

DefaultParameterConverter 是当 Stmt 没有实现ColumnConverter 时使用的 ValueConverter 的默认实现。

如果是 IsValue(arg)，DefaultParameterConverter 直接返回它的参数。否则，如果参数实现了 Valuer，则其 Value 方法用于返回值。作为回退，所提供的参数的基础类型用于将其转换为值：基础整数类型转换为 int64，浮动到 float64，bool，string 和 []byte。如果参数是一个零指针，ConvertValue 返回一个零值。如果参数是一个非零指针，则将其解除引用，并且递归地调用 ConvertValue 。其他类型是错误的。

var DefaultParameterConverter defaultConverter

ErrBadConn 应由驱动程序返回以向 sql 包发出信号，指出driver.Conn 处于不良状态（例如服务器先前已关闭连接），并且 sql 包应该在新连接上重试。

为防止重复操作，如果数据库服务器可能执行了操作，则不应返回 ErrBadConn。即使服务器发回错误，也不应返回 ErrBadConn。

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

可以从 NamedValueChecker 返回 ErrRemoveArgument 以指示 sql 包不将参数传递给驱动程序查询接口。当接受查询特定选项或不是 SQL 查询参数的结构时返回。

var ErrRemoveArgument = errors.New("driver: remove argument from query")

ErrSkip 可能会由一些可选接口的方法返回，以在运行时指示快速路径不可用，并且 sql 包应继续，就好像可选接口未实现一样。ErrSkip 仅在明确记录的情况下才受支持。

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

Int32 是一个 ValueConverter，它将输入值转换为 int64 ，并考虑到 int32 值的限制。

var Int32 int32Type

ResultNoRows 是驱动程序在 DDL 命令（例如 CREATE TABLE）成功时返回的预定义结果。它为 LastInsertId 和RowsAffected 都返回一个错误。

var ResultNoRows noRows

字符串是一个将其输入转换为字符串的 ValueConverter。如果该值已经是字符串或[]字节，则不会改变。如果该值是另一种类型，则使用 fmt.Sprintf（“％v”,v）完成对字符串的转换。

var String stringType

func IsScanValue（查看源代码）

func IsScanValue(v interface{}) bool

IsScanValue 等同于 IsValue。它存在的兼容性。

func IsValue（查看源代码）

func IsValue(v interface{}) bool

IsValue 报告 v 是否是有效的 Value 参数类型。

type ColumnConverter（查看源代码）

如果语句知道它自己的列的类型并且可以从任何类型转换为驱动程序的值，那么 ColumnConverter 可以选择由 Stmt 实现。

不推荐使用：驱动程序应该实现 NamedValueChecker 。

type ColumnConverter interface {
        // ColumnConverter为所提供的返回一个ValueConverter
        // 列索引（column index）。 如果特定列的类型未知
        // 或者不应该专门处理，DefaultValueConverter
        // 可以返回。
        ColumnConverter(idx int) ValueConverter
}

type Conn（查看源代码）

Conn 是与数据库的连接。它不是由多个 goroutine 同时使用。

Conn 被认为是有状态的。

type Conn interface {
        // Prepare返回一个准备好的语句，绑定到这个连接。
        Prepare(query string) (Stmt, error)

        // Close无效并可能停止任何当前
        // 准备好的陈述和交易，标记这一点
        // 连接不再使用。
        //
        // 因为sql包维护着一个空闲的池
        // 连接和只有调用在有剩余时关闭
        // 空闲的连接，它不应该是驱动程序需要
        // 做自己的连接缓存。
        Close() error

        // 开始并返回一个新的事务。
        //
        // 不推荐使用：驱动程序应该（或另外）实现ConnBeginTx。
        Begin() (Tx, error)
}

type ConnBeginTx（查看源代码）

ConnBeginTx 通过上下文和 TxOptions 增强了 Conn 接口。

type ConnBeginTx interface {
        // BeginTx启动并返回一个新的事务。
        // 如果上下文被用户取消，那么sql包会
        // 在丢弃和关闭连接之前调用Tx.Rollback。
        //
        // 这必须检查opts.Isolation以确定是否有一个集合
        // 隔离级别。 如果驱动程序不支持非默认
        // 级别和一个设置，或者如果有一个非默认的隔离级别
        // 如果不支持，则必须返回错误。
        //
        // 这还必须检查opts.ReadOnly以确定是否只读
        // 如果支持，则设置只读事务属性的值为true
        // 或者如果不支持则返回错误。
        BeginTx(ctx context.Context, opts TxOptions) (Tx, error)
}

type ConnPrepareContextSource

ConnPrepareContext 通过上下文增强了 Conn 接口。

type ConnPrepareContext interface {
        // PrepareContext返回一个准备好的语句，绑定到这个连接。
        // context是编写声明，
        // 它不能在语句本身内存储上下文。
        PrepareContext(ctx context.Context, query string) (Stmt, error)
}

type Driver（查看源代码）

驱动程序是必须由数据库驱动程序实现的接口。

type Driver interface {
        // 打开返回到数据库的新连接。
        // 该名称是一个驱动程序特定格式的字符串。
        //
        // 打开可能会返回一个缓存的连接（之前一个
        // 关闭），但这样做是不必要的; sql包
        // 维护一个空闲连接池以便有效地重用。
        //
        // 返回的连接仅由时间的一个goroutine使用
        // 时间。
        Open(name string) (Conn, error)
}

type Execer（查看源代码）

Execer 是一个可选接口，可由 Conn 实施。

如果 Conn 没有实现 Execer，那么 sql 包的 DB.Exec 将首先准备一个查询，执行该语句，然后关闭该语句。

Exec 可能会返回 ErrSkip。

弃用：驱动程序应该实现 ExecerContext （或另外）。

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

type ExecerContext（查看源代码）

ExecerContext 是一个可以由 Conn 实现的可选接口。

如果 Conn 没有实现 ExecerContext，sql 包的 DB.Exec 将首先准备一个查询，执行该语句，然后关闭该语句。

ExecerContext 可能会返回 ErrSkip。

ExecerContext 必须遵守上下文超时并在上下文被取消时返回。

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

type IsolationLevel（查看源代码）

IsolationLeve l是存储在 TxOptions 中的事务隔离级别。

这个类型应该被认为与 sql.IsolationLevel 以及在其上定义的任何值相同。

type IsolationLevel int

type NamedValue（查看源代码）

NamedValue 包含值名称和值。

type NamedValue struct {
        // 如果名称不是空的，它应该用于参数标识符和
        // 而不是次序位置。
        //
        // 名称不会有符号前缀。
        Name string

        // 从一开始的参数序号位置始终设置。
        Ordinal int

        // 值是参数值。
        Value Value
}

type NamedValueChecker（查看源代码）

NamedValueChecker 可以选择由 Conn 或 Stmt 实现。它为驱动程序提供了更多的控制来处理 Go 和数据库类型，超出了允许的默认值类型。

sql 包按以下顺序检查值检查器，在第一个找到的匹配处停止：Stmt.NamedValueChecker，Conn.NamedValueChecker，Stmt.ColumnConverter，DefaultParameterConverter。

如果 CheckNamedValue 返回 ErrRemoveArgument，那么NamedValue 将不会包含在最终的查询参数中。这可以用来将特殊选项传递给查询本身。

如果返回 ErrSkip ，则列转换器错误检查路径用于参数。驾驶员可能希望在用尽特殊情况后返回 ErrSkip。

type NamedValueChecker interface {
        // 在将参数传递给驱动程序之前调用CheckNamedValue
        // 并被调用来代替任何ColumnConverter。 CheckNamedValue必须输入
        // 验证和转换适合驱动程序。
        CheckNamedValue(*NamedValue) error
}

type NotNull（查看源代码）

NotNull 是一种类型，它通过禁止 nil 值来实现ValueConverter，否则委托给另一个 ValueConverter。

type NotNull struct {
        Converter ValueConverter
}

func (NotNull) ConvertValue（查看源代码）

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

type Null（查看源代码）

Null 是一种通过允许 nil 值实现 ValueConverter 的类型，但是可以委托给另一个 ValueConverter。

type Null struct {
        Converter ValueConverter
}

func (Null) ConvertValue（查看源代码）

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

type Pinger（查看源代码）

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
}

type Queryer（查看源代码）

Queryer 是一个可选的接口，可由 Conn 实施。

如果 Conn 没有实现 Queryer，那么 sql 包的 DB.Query 将首先准备一个查询，执行该语句，然后关闭该语句。

Query 可能会返回 ErrSkip。

弃用：驱动程序应该实现 QueryerContext（或另外）。

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

type QueryerContext（查看源代码）

QueryerContext 是一个可选接口，可由 Conn实施。

如果 Conn 没有实现 QueryerContext，则 sql 包的 DB.Query将首先准备一个查询，执行该语句，然后关闭该语句。

QueryerContext 可能会返回 ErrSkip。

QueryerContext 必须遵守上下文超时并在上下文被取消时返回。

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

type Result（查看源代码）

结果是查询执行的结果。

type Result interface {
        // LastInsertId返回数据库的自动生成的ID
        // 例如，在将一个INSERT插入到具有主要表的表中
        // 键（key）。
        LastInsertId() (int64, error)

        // RowsAffected返回受下列影响的行数
        RowsAffected() (int64, error)
}

type Rows（查看源代码）

行是对已执行的查询结果的迭代器。

type Rows interface {
        // 列将返回列的名称。 以下的数量
        // 结果的列从长度推断
        // slice。 如果某个特定的列名未知，则为空
        // 应该为该条目返回字符串。
        Columns() []string

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

        // 接下来被调用来填充下一行数据
        // 提供的切片(slice)。 提供的切片将是相同的
        // 大小与Columns()一样宽。
        //
        // 当没有更多行时，Next应返回io.EOF。
        Next(dest []Value) error
}

type RowsAffected（查看源代码）

RowsAffected 实现了一个 INSERT 或 UPDATE 操作的 Result，该操作使多行变异。

type RowsAffected int64

func (RowsAffected) LastInsertId（查看源代码）

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

func (RowsAffected) RowsAffected（查看源代码）

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

type RowsColumnTypeDatabaseTypeName（查看源代码）

RowsColumnTypeDatabaseTypeName 可以通过行来实现。它应该返回没有长度的数据库系统类型名称。类型名称应该是大写的。返回类型的示例："VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT", "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML", "TIMESTAMP"。

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

type RowsColumnTypeLength（查看源代码）

RowsColumnTypeLength 可以通过行来实现。如果列是可变长度类型，它应该返回列类型的长度。如果该列不是可变长度类型，则应返回 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)
}

type RowsColumnTypeNullable（查看源代码）

RowsColumnTypeNullable 可以由 Rows实现。如果已知列可能为空，则可为空的值应为 true ;如果列已知为不可空，则可为空值。如果列可空性未知，那么 ok 应该是错误的。

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

type RowsColumnTypePrecisionScale（查看源代码）

RowsColumnTypePrecisionScale 可以通过行来实现。它应该返回十进制类型的精度和小数位数。如果不适用，确定应该是错误的。以下是各种类型返回值的示例：

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)
}

type RowsColumnTypeScanType（查看源代码）

RowsColumnTypeScanType 可以通过行来实现。它应该返回可用于扫描类型的值类型。例如，数据库列类型 “bigint” 应该返回 “reflect.TypeOf(int64(0))”。

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

type RowsNextResultSet（查看源代码）

RowsNextResultSet 通过提供一种方式来通知驱动程序前进到下一个结果集，从而扩展了 Rows 接口。

type RowsNextResultSet interface {
        Rows

        // HasNextResultSet在当前结果集和结尾处被调用
        // 报告当前之后是否存在另一个结果集。
        HasNextResultSet() bool

        // NextResultSet将驱动程序提前到下一个结果集
        // 如果当前结果集中有剩余的行。
        //
        // 当没有更多的结果集时，NextResultSet应该返回io.EOF。
        NextResultSet() error
}

type Stmt（查看源代码）

Stmt 是一个准备好的声明。它与 Conn 绑定，并且不被多个goroutine 同时使用。

type Stmt interface {
        // Close关闭声明。
        //
        // 从Go 1.1开始，Stmt在使用时不会关闭
        // 任何查询。
        Close() error

        // NumInput返回占位符参数的数量。
        //
        // 如果NumInput returns> = 0，则sql包将进行完整性检查
        // 来自调用者的参数计数并将错误返回给调用者
        // 在语句的Exec或Query方法被调用之前。
        //
        // 如果驱动程序不知道，NumInput也可能返回-1
        // 其占位符的数量。 在那种情况下，sql包
        // 将不会执行检查Exec或Query参数计数。
        NumInput() int

        // Exec执行不返回行的查询，例如
        // INSERT或UPDATE。
        //
        // 弃用（Deprecated）：驱动程序应该实现StmtExecContext（或另外）。

        // Query执行可能返回行的查询，例如一个
        // SELECT。
        //
        // 弃用（Deprecated）：驱动程序应该实现StmtQueryContext（或另外）。
        Query(args []Value) (Rows, error)
}

type StmtExecContext（查看源代码）

StmtExecContext 通过向 Exec 提供上下文来增强 Stmt 接口。

type StmtExecContext interface {
        // ExecContext执行不返回行的查询，例如
        // INSERT或UPDATE。
        //
        // ExecContext 必须遵守上下文超时并在取消时返回。
        ExecContext(ctx context.Context, args []NamedValue) (Result, error)
}

type StmtQueryContext（查看源代码）

StmtQueryContext 通过提供具有上下文的查询来增强 Stmt 接口。

type StmtQueryContext interface {
        // QueryContext执行一个可能返回行的查询，比如
        // SELECT。
        //
        // QueryContext必须遵守上下文超时并在取消时返回。
        QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
}

type Tx（查看源代码）

Tx 是一项交易。

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

type TxOptions（查看源代码）

TxOptions 持有交易选项。

这种类型应该被认为与 sql.TxOptions 相同。

type TxOptions struct {
        Isolation IsolationLevel
        ReadOnly  bool
}

type Value（查看源代码）

Value 是司机必须能够处理的价值。它可以是零或是其中一种类型的实例：

int64
float64
bool
[]byte
string
time.Time

type Value interface{}

type ValueConverter（查看源代码）

ValueConverter 是提供 ConvertValue 方法的接口。

ValueConverter 的各种实现由驱动程序包提供，以提供驱动程序之间转换的一致实现。ValueConverters 有几个用途：

*从sql包提供的值类型转换
  到数据库表的特定列类型并确保它
  适合，比如确保一个特定的int64适合a
  表的uint16列。

*将数据库中给定的值转换为
  驱动程序值类型。

*由sql包提供，用于从驱动程序的Value类型转换
  扫描到用户的类型。

type ValueConverter interface {
        // ConvertValue将值转换为驱动程序值。
        ConvertValue(v interface{}) (Value, error)
}

type Valuer（查看源代码）

Valuer 是提供 Value 方法的界面。

实现 Valuer 接口的类型能够将自己转换为驱动程序 Value。

type Valuer interface {
        // 值返回一个驱动程序的值。
        Value() (Value, error)
}