©
This document uses PHP Chinese website manual Release
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(v interface{}) boolIsScanValue 等同于 IsValue。它存在的兼容性。
func IsValue(v interface{}) boolIsValue 报告 v 是否是有效的 Value 参数类型。
如果语句知道它自己的列的类型并且可以从任何类型转换为驱动程序的值，那么 ColumnConverter 可以选择由 Stmt 实现。
不推荐使用：驱动程序应该实现 NamedValueChecker 。
type ColumnConverter interface { // ColumnConverter为所提供的返回一个ValueConverter // 列索引（column index）。 如果特定列的类型未知 // 或者不应该专门处理，DefaultValueConverter // 可以返回。 ColumnConverter(idx int) ValueConverter}Conn 是与数据库的连接。它不是由多个 goroutine 同时使用。
Conn 被认为是有状态的。
type Conn interface { // Prepare返回一个准备好的语句，绑定到这个连接。 Prepare(query string) (Stmt, error) // Close无效并可能停止任何当前 // 准备好的陈述和交易，标记这一点 // 连接不再使用。 // // 因为sql包维护着一个空闲的池 // 连接和只有调用在有剩余时关闭 // 空闲的连接，它不应该是驱动程序需要 // 做自己的连接缓存。 Close() error // 开始并返回一个新的事务。 // // 不推荐使用：驱动程序应该（或另外）实现ConnBeginTx。 Begin() (Tx, error)}ConnBeginTx 通过上下文和 TxOptions 增强了 Conn 接口。
type ConnBeginTx interface { // BeginTx启动并返回一个新的事务。 // 如果上下文被用户取消，那么sql包会 // 在丢弃和关闭连接之前调用Tx.Rollback。 // // 这必须检查opts.Isolation以确定是否有一个集合 // 隔离级别。 如果驱动程序不支持非默认 // 级别和一个设置，或者如果有一个非默认的隔离级别 // 如果不支持，则必须返回错误。 // // 这还必须检查opts.ReadOnly以确定是否只读 // 如果支持，则设置只读事务属性的值为true // 或者如果不支持则返回错误。 BeginTx(ctx context.Context, opts TxOptions) (Tx, error)}ConnPrepareContext 通过上下文增强了 Conn 接口。
type ConnPrepareContext interface { // PrepareContext返回一个准备好的语句，绑定到这个连接。 // context是编写声明， // 它不能在语句本身内存储上下文。 PrepareContext(ctx context.Context, query string) (Stmt, error)}驱动程序是必须由数据库驱动程序实现的接口。
type Driver interface { // 打开返回到数据库的新连接。 // 该名称是一个驱动程序特定格式的字符串。 // // 打开可能会返回一个缓存的连接（之前一个 // 关闭），但这样做是不必要的; sql包 // 维护一个空闲连接池以便有效地重用。 // // 返回的连接仅由时间的一个goroutine使用 // 时间。 Open(name string) (Conn, error)}Execer 是一个可选接口，可由 Conn 实施。
如果 Conn 没有实现 Execer，那么 sql 包的 DB.Exec 将首先准备一个查询，执行该语句，然后关闭该语句。
Exec 可能会返回 ErrSkip。
弃用：驱动程序应该实现 ExecerContext （或另外）。
type Execer interface { Exec(query string, args []Value) (Result, error)}ExecerContext 是一个可以由 Conn 实现的可选接口。
如果 Conn 没有实现 ExecerContext，sql 包的 DB.Exec 将首先准备一个查询，执行该语句，然后关闭该语句。
ExecerContext 可能会返回 ErrSkip。
ExecerContext 必须遵守上下文超时并在上下文被取消时返回。
type ExecerContext interface { ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)}IsolationLeve l是存储在 TxOptions 中的事务隔离级别。
这个类型应该被认为与 sql.IsolationLevel 以及在其上定义的任何值相同。
type IsolationLevel int
NamedValue 包含值名称和值。
type NamedValue struct { // 如果名称不是空的，它应该用于参数标识符和 // 而不是次序位置。 // // 名称不会有符号前缀。
Name string // 从一开始的参数序号位置始终设置。
Ordinal int // 值是参数值。
Value Value}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}NotNull 是一种类型，它通过禁止 nil 值来实现ValueConverter，否则委托给另一个 ValueConverter。
type NotNull struct {
Converter ValueConverter}func (n NotNull) ConvertValue(v interface{}) (Value, error)Null 是一种通过允许 nil 值实现 ValueConverter 的类型，但是可以委托给另一个 ValueConverter。
type Null struct {
Converter ValueConverter}func (n Null) ConvertValue(v interface{}) (Value, error)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}Queryer 是一个可选的接口，可由 Conn 实施。
如果 Conn 没有实现 Queryer，那么 sql 包的 DB.Query 将首先准备一个查询，执行该语句，然后关闭该语句。
Query 可能会返回 ErrSkip。
弃用：驱动程序应该实现 QueryerContext（或另外）。
type Queryer interface { Query(query string, args []Value) (Rows, error)}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 interface { // LastInsertId返回数据库的自动生成的ID // 例如，在将一个INSERT插入到具有主要表的表中 // 键（key）。 LastInsertId() (int64, error) // RowsAffected返回受下列影响的行数 RowsAffected() (int64, error)}行是对已执行的查询结果的迭代器。
type Rows interface { // 列将返回列的名称。 以下的数量 // 结果的列从长度推断 // slice。 如果某个特定的列名未知，则为空 // 应该为该条目返回字符串。 Columns() []string // Close关闭行迭代器。 Close() error // 接下来被调用来填充下一行数据 // 提供的切片(slice)。 提供的切片将是相同的 // 大小与Columns()一样宽。 // // 当没有更多行时，Next应返回io.EOF。 Next(dest []Value) error}RowsAffected 实现了一个 INSERT 或 UPDATE 操作的 Result，该操作使多行变异。
type RowsAffected int64
func (RowsAffected) LastInsertId() (int64, error)
func (v RowsAffected) RowsAffected() (int64, error)
RowsColumnTypeDatabaseTypeName 可以通过行来实现。它应该返回没有长度的数据库系统类型名称。类型名称应该是大写的。返回类型的示例："VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT", "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML", "TIMESTAMP"。
type RowsColumnTypeDatabaseTypeName interface {
Rows ColumnTypeDatabaseTypeName(index int) string}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)}RowsColumnTypeNullable 可以由 Rows实现。如果已知列可能为空，则可为空的值应为 true ;如果列已知为不可空，则可为空值。如果列可空性未知，那么 ok 应该是错误的。
type RowsColumnTypeNullable interface {
Rows ColumnTypeNullable(index int) (nullable, ok bool)}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)}RowsColumnTypeScanType 可以通过行来实现。它应该返回可用于扫描类型的值类型。例如，数据库列类型 “bigint” 应该返回 “reflect.TypeOf(int64(0))”。
type RowsColumnTypeScanType interface {
Rows ColumnTypeScanType(index int) reflect.Type}RowsNextResultSet 通过提供一种方式来通知驱动程序前进到下一个结果集，从而扩展了 Rows 接口。
type RowsNextResultSet interface {
Rows // HasNextResultSet在当前结果集和结尾处被调用 // 报告当前之后是否存在另一个结果集。 HasNextResultSet() bool // NextResultSet将驱动程序提前到下一个结果集 // 如果当前结果集中有剩余的行。 // // 当没有更多的结果集时，NextResultSet应该返回io.EOF。 NextResultSet() error}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)}import "database/sql"
概述
索引
示例
子目录
Package sql 提供了一个围绕SQL（或类似SQL）数据库的通用接口。
sql 包必须与数据库驱动程序一起使用。查看https://golang.org/s/sqldrivers获取驱动程序列表。
不支持上下文取消的驱动程序直到查询完成后才会返回。
有关使用示例，请参阅https://golang.org/s/sqlwiki上的wiki页面。
Variables
func Drivers() []string
func Register(name string, driver driver.Driver)
type ColumnType
func (ci *ColumnType) DatabaseTypeName() string
func (ci *ColumnType) DecimalSize() (precision, scale int64, ok bool)
func (ci *ColumnType) Length() (length int64, ok bool)
func (ci *ColumnType) Name() string
func (ci *ColumnType) Nullable() (nullable, ok bool)
func (ci *ColumnType) ScanType() reflect.Type
type Conn
func (c *Conn) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)
func (c *Conn) Close() error
func (c *Conn) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)
func (c *Conn) PingContext(ctx context.Context) error