Package sql

import "database/sql"
Overview
Index
Examples
Subdirectories

Overview ▾

包sql提供了围绕SQL(或类似SQL)数据库的通用接口.

sql程序包必须与数据库驱动程序一起使用. 有关驱动程序列表,请参见https://golang.org/s/sqldrivers .

在查询完成后,不支持上下文取消的驱动程序将不会返回.

有关用法示例,请参见Wiki页面, 网址https://golang.org/s/sqlwiki .

范例(OpenDBCLI)

示例(OpenDBService)

Index ▾

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
    func (c *Conn) PrepareContext(ctx context.Context, query string) (*Stmt, error)
    func (c *Conn) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)
    func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row
    func (c *Conn) Raw(f func(driverConn interface{}) error) (err error)
type DB
    func Open(driverName, dataSourceName string) (*DB, error)
    func OpenDB(c driver.Connector) *DB
    func (db *DB) Begin() (*Tx, error)
    func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)
    func (db *DB) Close() error
    func (db *DB) Conn(ctx context.Context) (*Conn, error)
    func (db *DB) Driver() driver.Driver
    func (db *DB) Exec(query string, args ...interface{}) (Result, error)
    func (db *DB) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)
    func (db *DB) Ping() error
    func (db *DB) PingContext(ctx context.Context) error
    func (db *DB) Prepare(query string) (*Stmt, error)
    func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error)
    func (db *DB) Query(query string, args ...interface{}) (*Rows, error)
    func (db *DB) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)
    func (db *DB) QueryRow(query string, args ...interface{}) *Row
    func (db *DB) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row
    func (db *DB) SetConnMaxLifetime(d time.Duration)
    func (db *DB) SetMaxIdleConns(n int)
    func (db *DB) SetMaxOpenConns(n int)
    func (db *DB) Stats() DBStats
type DBStats
type IsolationLevel
    func (i IsolationLevel) String() string
type NamedArg
    func Named(name string, value interface{}) NamedArg
type NullBool
    func (n *NullBool) Scan(value interface{}) error
    func (n NullBool) Value() (driver.Value, error)
type NullFloat64
    func (n *NullFloat64) Scan(value interface{}) error
    func (n NullFloat64) Value() (driver.Value, error)
type NullInt32
    func (n *NullInt32) Scan(value interface{}) error
    func (n NullInt32) Value() (driver.Value, error)
type NullInt64
    func (n *NullInt64) Scan(value interface{}) error
    func (n NullInt64) Value() (driver.Value, error)
type NullString
    func (ns *NullString) Scan(value interface{}) error
    func (ns NullString) Value() (driver.Value, error)
type NullTime
    func (n *NullTime) Scan(value interface{}) error
    func (n NullTime) Value() (driver.Value, error)
type Out
type RawBytes
type Result
type Row
    func (r *Row) Scan(dest ...interface{}) error
type Rows
    func (rs *Rows) Close() error
    func (rs *Rows) ColumnTypes() ([]*ColumnType, error)
    func (rs *Rows) Columns() ([]string, error)
    func (rs *Rows) Err() error
    func (rs *Rows) Next() bool
    func (rs *Rows) NextResultSet() bool
    func (rs *Rows) Scan(dest ...interface{}) error
type Scanner
type Stmt
    func (s *Stmt) Close() error
    func (s *Stmt) Exec(args ...interface{}) (Result, error)
    func (s *Stmt) ExecContext(ctx context.Context, args ...interface{}) (Result, error)
    func (s *Stmt) Query(args ...interface{}) (*Rows, error)
    func (s *Stmt) QueryContext(ctx context.Context, args ...interface{}) (*Rows, error)
    func (s *Stmt) QueryRow(args ...interface{}) *Row
    func (s *Stmt) QueryRowContext(ctx context.Context, args ...interface{}) *Row
type Tx
    func (tx *Tx) Commit() error
    func (tx *Tx) Exec(query string, args ...interface{}) (Result, error)
    func (tx *Tx) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)
    func (tx *Tx) Prepare(query string) (*Stmt, error)
    func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error)
    func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error)
    func (tx *Tx) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)
    func (tx *Tx) QueryRow(query string, args ...interface{}) *Row
    func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row
    func (tx *Tx) Rollback() error
    func (tx *Tx) Stmt(stmt *Stmt) *Stmt
    func (tx *Tx) StmtContext(ctx context.Context, stmt *Stmt) *Stmt
type TxOptions

Package files

convert.go ctxutil.go sql.go

Variables

对已经返回到连接池的连接执行的任何操作都将返回ErrConnDone.

var ErrConnDone = errors.New("sql: connection is already closed")

当QueryRow不返回行时,Scan将返回ErrNoRows. 在这种情况下,QueryRow返回一个占位符* Row值,该值将这个错误推迟到Scan为止.

var ErrNoRows = errors.New("sql: no rows in result set")

对已落实或回滚的事务执行的任何操作都将返回ErrTxDone.

var ErrTxDone = errors.New("sql: transaction has already been committed or rolled back")

func Drivers 1.4

func Drivers() []string

驱动程序返回已注册驱动程序名称的排序列表.

func Register

func Register(name string, driver driver.Driver)

注册通过提供的名称使数据库驱动程序可用. 如果使用相同的名称两次调用Register或驱动程序为nil,则会出现紧急情况.

type ColumnType 1.8

ColumnType包含列的名称和类型.

type ColumnType struct {
    // contains filtered or unexported fields
}

func (*ColumnType) DatabaseTypeName 1.8

func (ci *ColumnType) DatabaseTypeName() string

DatabaseTypeName返回列类型的数据库系统名称. 如果返回空字符串,则不支持驱动程序类型名称. 请查阅驱动程序文档以获取驱动程序数据类型的列表. 不包括长度说明符. 常见类型包括" VARCHAR"," TEXT"," NVARCHAR"," DECIMAL"," BOOL"," INT"," BIGINT".

func (*ColumnType) DecimalSize 1.8

func (ci *ColumnType) DecimalSize() (precision, scale int64, ok bool)

DecimalSize返回小数类型的小数位数和精度. 如果不适用或不支持,则ok为false.

func (*ColumnType) Length 1.8

func (ci *ColumnType) Length() (length int64, ok bool)

Length返回可变长度列类型(例如文本和二进制字段类型)的列类型长度. 如果类型长度不​​受限制,则该值将为math.MaxInt64(任何数据库限制仍然适用). 如果列类型不是可变长度(例如int),或者驱动程序不支持ok,则为false.

func (*ColumnType) Name 1.8

func (ci *ColumnType) Name() string

名称返回列的名称或别名.

func (*ColumnType) Nullable 1.8

func (ci *ColumnType) Nullable() (nullable, ok bool)

可为空的报告列是否可以为空. 如果驱动程序不支持此属性,则ok将为false.

func (*ColumnType) ScanType 1.8

func (ci *ColumnType) ScanType() reflect.Type

ScanType返回适合使用Rows.Scan进行扫描的Go类型. 如果驱动程序不支持此属性,则ScanType将返回空接口的类型.

type Conn 1.9

Conn表示单个数据库连接,而不是数据库连接池. 除非特别需要连续的单个数据库连接,否则最好从数据库运行查询.

Conn必须调用Close才能将连接返回数据库池,并且可以与正在运行的查询同时进行.

调用"关闭"后,对该连接的所有操作都将失败,并显示ErrConnDone.

type Conn struct {
    // contains filtered or unexported fields
}

func (*Conn) BeginTx 1.9

func (c *Conn) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)

Begin TX开始交易.

在事务提交或回滚之前,将使用提供的上下文. 如果上下文被取消,则sql包将回滚事务. 如果取消提供给BeginTx的上下文,则Tx.Commit将返回错误.

提供的TxOptions是可选的,如果应使用默认值,则可以为nil. 如果使用了驱动程序不支持的非默认隔离级别,则将返回错误.

Example

func (*Conn) Close 1.9

func (c *Conn) Close() error

关闭将连接返回到连接池. 关闭后的所有操作将通过ErrConnDone返回. 关闭可以安全地与其他操作同时调用,并且将阻塞直到所有其他操作完成. 首先取消任何使用的上下文,然后再直接调用close可能很有用.

func (*Conn) ExecContext 1.9

func (c *Conn) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)

ExecContext执行查询而不返回任何行. args用于查询中的任何占位符参数.

Example

func (*Conn) PingContext 1.9

func (c *Conn) PingContext(ctx context.Context) error

PingContext验证与数据库的连接是否仍然有效.

func (*Conn) PrepareContext 1.9

func (c *Conn) PrepareContext(ctx context.Context, query string) (*Stmt, error)

PrepareContext为以后的查询或执行创建准备好的语句. 可以从返回的语句中并发运行多个查询或执行. 当不再需要该语句时,调用方必须调用该语句的Close方法.

提供的上下文用于语句的准备,而不是语句的执行.

func (*Conn) QueryContext 1.9

func (c *Conn) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)

QueryContext执行一个查询,该查询返回行,通常是SELECT. args用于查询中的任何占位符参数.

func (*Conn) QueryRowContext 1.9

func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row

QueryRowContext执行的查询预期最多返回一行. QueryRowContext始终返回非nil值. 错误将延迟到调用Row的Scan方法之前. 如果查询未选择任何行,则"行扫描"将返回ErrNoRows. 否则,*行扫描将扫描所选的第一行,并丢弃其余的行.

func (*Conn) Raw 1.13

func (c *Conn) Raw(f func(driverConn interface{}) error) (err error)

Raw执行f,在f的持续时间内公开基础驱动程序连接. driverConn不能在f之外使用.

一旦f返回并且err为nil,则Conn将继续可用,直到调用Conn.Close为止.

type DB

DB是代表零个或多个基础连接池的数据库句柄. 对于多个goroutine并发使用是安全的.

sql软件包会自动创建并释放连接. 它还维护空闲连接的空闲池. 如果数据库具有按连接状态的概念,则可以在事务(Tx)或连接(Conn)中可靠地观察到这种状态. 调用DB.Begin之后,返回的Tx将绑定到单个连接. 一旦在事务上调用了Commit或Rollback,该事务的连接将返回到DB的空闲连接池. 池大小可以通过SetMaxIdleConns控制.

type DB struct {
    // contains filtered or unexported fields
}

func Open

func Open(driverName, dataSourceName string) (*DB, error)

Open打开一个由其数据库驱动程序名称和特定于驱动程序的数据源名称指定的数据库,该名称通常至少由数据库名称和连接信息组成.

大多数用户将通过特定于驱动程序的连接帮助程序函数来打开数据库,该函数返回* DB. Go标准库中没有数据库驱动程序. 有关第三方驱动程序的列表,请参见https://golang.org/s/sqldrivers .

Open可能只验证其参数而不创建与数据库的连接. 要验证数据源名称是否有效,请致电Ping.

返回的数据库可安全地供多个goroutine并发使用,并维护其自己的空闲连接池. 因此,Open函数应仅被调用一次. 很少需要关闭数据库.

func OpenDB 1.10

func OpenDB(c driver.Connector) *DB

OpenDB使用连接器打开数据库,从而允许驱动程序绕过基于字符串的数据源名称.

大多数用户将通过特定于驱动程序的连接帮助程序函数来打开数据库,该函数返回* DB. Go标准库中没有数据库驱动程序. 有关第三方驱动程序的列表,请参见https://golang.org/s/sqldrivers .

OpenDB可能只验证其参数而不创建与数据库的连接. 要验证数据源名称是否有效,请致电Ping.

返回的数据库可安全地供多个goroutine并发使用,并维护其自己的空闲连接池. 因此,OpenDB函数应该仅被调用一次. 很少需要关闭数据库.

func (*DB) Begin

func (db *DB) Begin() (*Tx, error)

开始开始交易. 默认隔离级别取决于驱动程序.

func (*DB) BeginTx 1.8

func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)

BeginTx starts a transaction.

在事务提交或回滚之前,将使用提供的上下文. 如果上下文被取消,则sql包将回滚事务. 如果取消提供给BeginTx的上下文,则Tx.Commit将返回错误.

提供的TxOptions是可选的,如果应使用默认值,则可以为nil. 如果使用了驱动程序不支持的非默认隔离级别,则将返回错误.

func (*DB) Close

func (db *DB) Close() error

关闭将关闭数据库并阻止启动新查询. 关闭,然后等待所有已开始在服务器上处理的查询完成.

关闭数据库很少,因为该数据库句柄是长期存在的并且在许多goroutine之间共享.

func (*DB) Conn 1.9

func (db *DB) Conn(ctx context.Context) (*Conn, error)

Conn通过打开新连接或从连接池返回现有连接来返回单个连接. Conn将阻塞,直到返回连接或取消ctx. 在同一Conn上运行的查询将在同一数据库会话中运行.

使用后,必须通过调用Conn.Close将每个Conn返回到数据库池.

func (*DB) Driver

func (db *DB) Driver() driver.Driver

驱动程序返回数据库的基础驱动程序.

func (*DB) Exec

func (db *DB) Exec(query string, args ...interface{}) (Result, error)

Exec执行查询而不返回任何行. args用于查询中的任何占位符参数.

func (*DB) ExecContext 1.8

func (db *DB) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)

ExecContext executes a query without returning any rows. The args are for any placeholder parameters in the query.

Example

func (*DB) Ping 1.1

func (db *DB) Ping() error

Ping验证到数据库的连接仍然有效,并在必要时建立连接.

func (*DB) PingContext 1.8

func (db *DB) PingContext(ctx context.Context) error

PingContext验证与数据库的连接是否仍然存在,并在必要时建立连接.

Example

func (*DB) Prepare

func (db *DB) Prepare(query string) (*Stmt, error)

Prepare为以后的查询或执行创建一个准备好的语句. 可以从返回的语句中并发运行多个查询或执行. 当不再需要该语句时,调用方必须调用该语句的Close方法.

Example

func (*DB) PrepareContext 1.8

func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error)

PrepareContext为以后的查询或执行创建准备好的语句. 可以从返回的语句中并发运行多个查询或执行. 当不再需要该语句时,调用方必须调用该语句的Close方法.

提供的上下文用于语句的准备,而不是语句的执行.

func (*DB) Query

func (db *DB) Query(query string, args ...interface{}) (*Rows, error)

查询执行返回行的查询,通常为SELECT. args用于查询中的任何占位符参数.

示例(MultipleResultSets)

func (*DB) QueryContext 1.8

func (db *DB) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)

QueryContext executes a query that returns rows, typically a SELECT. The args are for any placeholder parameters in the query.

Example

func (*DB) QueryRow

func (db *DB) QueryRow(query string, args ...interface{}) *Row

QueryRow执行的查询预期最多返回一行. QueryRow始终返回非nil值. 错误将延迟到调用Row的Scan方法之前. 如果查询未选择任何行,则"行扫描"将返回ErrNoRows. 否则,*行扫描将扫描所选的第一行,并丢弃其余的行.

func (*DB) QueryRowContext 1.8

func (db *DB) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row

QueryRowContext执行的查询预期最多返回一行. QueryRowContext始终返回非nil值. 错误将延迟到调用Row的Scan方法之前. 如果查询未选择任何行,则"行扫描"将返回ErrNoRows. 否则,*行扫描将扫描所选的第一行,并丢弃其余的行.

Example

func (*DB) SetConnMaxLifetime 1.6

func (db *DB) SetConnMaxLifetime(d time.Duration)

SetConnMaxLifetime设置可以重用连接的最长时间.

过期的连接可以在重新使用之前延迟关闭.

如果d <= 0,则连接将永远重复使用.

func (*DB) SetMaxIdleConns 1.1

func (db *DB) SetMaxIdleConns(n int)

SetMaxIdleConns设置空闲连接池中的最大连接数.

如果MaxOpenConns大于0但小于新的MaxIdleConns,则新的MaxIdleConns将减少以匹配MaxOpenConns限制.

如果n <= 0,则不保留空闲连接.

当前的默认最大空闲连接数为2.在将来的版本中可能会更改.

func (*DB) SetMaxOpenConns 1.2

func (db *DB) SetMaxOpenConns(n int)

SetMaxOpenConns设置与数据库的最大打开连接数.

如果MaxIdleConns大于0并且新的MaxOpenConns小于MaxIdleConns,则MaxIdleConns将减少以匹配新的MaxOpenConns限制.

如果n <= 0,则打开的连接数没有限制. 默认值为0(无限制).

func (*DB) Stats 1.5

func (db *DB) Stats() DBStats

Stats返回数据库统计信息.

type DBStats 1.5

DBStats包含数据库统计信息.

type DBStats struct {
    MaxOpenConnections int // Maximum number of open connections to the database; added in Go 1.11

    // Pool Status
    OpenConnections int // The number of established connections both in use and idle.
    InUse           int // The number of connections currently in use; added in Go 1.11
    Idle            int // The number of idle connections; added in Go 1.11

    // Counters
    WaitCount         int64         // The total number of connections waited for; added in Go 1.11
    WaitDuration      time.Duration // The total time blocked waiting for a new connection; added in Go 1.11
    MaxIdleClosed     int64         // The total number of connections closed due to SetMaxIdleConns; added in Go 1.11
    MaxLifetimeClosed int64         // The total number of connections closed due to SetConnMaxLifetime; added in Go 1.11
}

type IsolationLevel 1.8

IsolationLevel是TxOptions中使用的事务隔离级别.

type IsolationLevel int

驱动程序可以在BeginTx中支持的各种隔离级别. 如果驱动程序不支持给定的隔离级别,则可能会返回错误.

See https://en.wikipedia.org/wiki/Isolation_(database_systems)#Isolation_levels.

const (
    LevelDefault IsolationLevel = iota
    LevelReadUncommitted
    LevelReadCommitted
    LevelWriteCommitted
    LevelRepeatableRead
    LevelSnapshot
    LevelSerializable
    LevelLinearizable
)

func (IsolationLevel) String 1.11

func (i IsolationLevel) String() string

字符串返回事务隔离级别的名称.

type NamedArg 1.8

NamedArg是一个命名参数. NamedArg值可用作Query或Exec的参数,并绑定到SQL语句中的相应命名参数.

有关创建NamedArg值的更简洁的方法,请参见Named函数.

type NamedArg struct {

    // Name is the name of the parameter placeholder.
    //
    // If empty, the ordinal position in the argument list will be
    // used.
    //
    // Name must omit any symbol prefix.
    Name string

    // Value is the value of the parameter.
    // It may be assigned the same value types as the query
    // arguments.
    Value interface{}
    // contains filtered or unexported fields
}

func Named 1.8

func Named(name string, value interface{}) NamedArg

Named提供了一种更简洁的方法来创建NamedArg值.

用法示例:

db.ExecContext(ctx, `
    delete from Invoice
    where
        TimeCreated < @end
        and TimeCreated >= @start;`,
    sql.Named("start", startTime),
    sql.Named("end", endTime),
)

type NullBool

NullBool表示布尔值,可以为null. NullBool实现了Scanner接口,因此可以将其用作扫描目标,类似于NullString.

type NullBool struct {
    Bool  bool
    Valid bool // Valid is true if Bool is not NULL
}

func (*NullBool) Scan

func (n *NullBool) Scan(value interface{}) error

扫描实现扫描仪界面.

func (NullBool) Value

func (n NullBool) Value() (driver.Value, error)

Value实现驱动程序Valuer接口.

type NullFloat64

NullFloat64表示可以为null的float64. NullFloat64实现了Scanner接口,因此可以将其用作扫描目标,类似于NullString.

type NullFloat64 struct {
    Float64 float64
    Valid   bool // Valid is true if Float64 is not NULL
}

func (*NullFloat64) Scan

func (n *NullFloat64) Scan(value interface{}) error

扫描实现扫描仪界面.

func (NullFloat64) Value

func (n NullFloat64) Value() (driver.Value, error)

Value实现驱动程序Valuer接口.

type NullInt32 1.13

NullInt32表示可能为null的int32. NullInt32实现了Scanner接口,因此可以将其用作扫描目标,类似于NullString.

type NullInt32 struct {
    Int32 int32
    Valid bool // Valid is true if Int32 is not NULL
}

func (*NullInt32) Scan 1.13

func (n *NullInt32) Scan(value interface{}) error

扫描实现扫描仪界面.

func (NullInt32) Value 1.13

func (n NullInt32) Value() (driver.Value, error)

Value实现驱动程序Valuer接口.

type NullInt64

NullInt64表示可能为null的int64. NullInt64实现了Scanner接口,因此可以将其用作扫描目标,类似于NullString.

type NullInt64 struct {
    Int64 int64
    Valid bool // Valid is true if Int64 is not NULL
}

func (*NullInt64) Scan

func (n *NullInt64) Scan(value interface{}) error

扫描实现扫描仪界面.

func (NullInt64) Value

func (n NullInt64) Value() (driver.Value, error)

Value实现驱动程序Valuer接口.

type NullString

NullString表示可能为空的字符串. NullString实现了Scanner接口,因此可以将其用作扫描目标:

var s NullString
err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s)
...
if s.Valid {
   // use s.String
} else {
   // NULL value
}
type NullString struct {
    String string
    Valid  bool // Valid is true if String is not NULL
}

func (*NullString) Scan

func (ns *NullString) Scan(value interface{}) error

扫描实现扫描仪界面.

func (NullString) Value

func (ns NullString) Value() (driver.Value, error)

Value实现驱动程序Valuer接口.

type NullTime 1.13

NullTime表示时间.时间可能为null. NullTime实现了Scanner接口,因此可以将其用作扫描目标,类似于NullString.

type NullTime struct {
    Time  time.Time
    Valid bool // Valid is true if Time is not NULL
}

func (*NullTime) Scan 1.13

func (n *NullTime) Scan(value interface{}) error

扫描实现扫描仪界面.

func (NullTime) Value 1.13

func (n NullTime) Value() (driver.Value, error)

Value实现驱动程序Valuer接口.

type Out 1.9

Out可用于从存储过程中检索OUTPUT值参数.

并非所有驱动程序和数据库都支持OUTPUT值参数.

用法示例:

var outArg string
_, err := db.ExecContext(ctx, "ProcName", sql.Named("Arg1", sql.Out{Dest: &outArg}))
type Out struct {

    // Dest is a pointer to the value that will be set to the result of the
    // stored procedure's OUTPUT parameter.
    Dest interface{}

    // In is whether the parameter is an INOUT parameter. If so, the input value to the stored
    // procedure is the dereferenced value of Dest's pointer, which is then replaced with
    // the output value.
    In bool
    // contains filtered or unexported fields
}

type RawBytes

RawBytes是一个字节片,其中包含对数据库本身拥有的内存的引用. 扫描到RawBytes之后,该切片仅在下一次调用Next,Scan或Close之前有效.

type RawBytes []byte

type Result

结果汇总了已执行的SQL命令.

type Result interface {
    // LastInsertId returns the integer generated by the database
    // in response to a command. Typically this will be from an
    // "auto increment" column when inserting a new row. Not all
    // databases support this feature, and the syntax of such
    // statements varies.
    LastInsertId() (int64, error)

    // RowsAffected returns the number of rows affected by an
    // update, insert, or delete. Not every database or database
    // driver may support this.
    RowsAffected() (int64, error)
}

type Row

行是调用QueryRow选择单个行的结果.

type Row struct {
    // contains filtered or unexported fields
}

func (*Row) Scan

func (r *Row) Scan(dest ...interface{}) error

扫描将匹配的行中的列复制到dest指向的值中. 有关详细信息,请参见Rows.Scan上的文档. 如果与查询匹配的行超过一个,则Scan使用第一行,并丢弃其余行. 如果没有行与查询匹配,则Scan返回ErrNoRows.

type Rows

行是查询的结果. 它的光标从结果集的第一行开始. 使用"下一步"在每一行中前进.

type Rows struct {
    // contains filtered or unexported fields
}

Example

func (*Rows) Close

func (rs *Rows) Close() error

Close关闭行,防止进一步枚举. 如果调用Next并返回false,并且没有其他结果集,则将自动关闭行,这将足以检查Err的结果. 关闭是幂等的,不会影响Err的结果.

func (*Rows) ColumnTypes 1.8

func (rs *Rows) ColumnTypes() ([]*ColumnType, error)

ColumnTypes返回列信息,例如列类型,长度和可为空. 某些驱动程序可能无法提供某些信息.

func (*Rows) Columns

func (rs *Rows) Columns() ([]string, error)

Columns returns the column names. Columns returns an error if the rows are closed.

func (*Rows) Err

func (rs *Rows) Err() error

Err返回在迭代过程中遇到的错误(如果有). 可以在显式或隐式Close之后调用Err.

func (*Rows) Next

func (rs *Rows) Next() bool

Next准备下一个结果行,以使用Scan方法读取. 如果成功,它将返回true;如果没有下一个结果行或在准备它时发生错误,则返回false. 应咨询Err来区分这两种情况.

每次致电Scan,甚至是第一个,都必须先致电Next.

func (*Rows) NextResultSet 1.8

func (rs *Rows) NextResultSet() bool

NextResultSet准备下一个要读取的结果集. 它报告是否还有其他结果集,如果没有其他结果集或前进时出现错误,则报告false. 应该使用Err方法来区分这两种情况.

调用NextResultSet之后,应始终在扫描之前调用Next方法. 如果还有其他结果集,则结果集中可能没有行.

func (*Rows) Scan

func (rs *Rows) Scan(dest ...interface{}) error

扫描将当前行中的列复制到dest指向的值中. dest中的值数必须与"行"中的列数相同.

扫描将从数据库读取的列转换为以下常见的Go类型和sql包提供的特殊类型:

*string
*[]byte
*int, *int8, *int16, *int32, *int64
*uint, *uint8, *uint16, *uint32, *uint64
*bool
*float32, *float64
*interface{}
*RawBytes
*Rows (cursor value)
any type implementing Scanner (see Scanner docs)

在最简单的情况下,如果源列中的值的类型是整数,布尔型或字符串类型T,而dest的类型是* T,则Scan仅通过指针分配值.

只要不丢失任何信息,扫描还会在字符串和数字类型之间转换. 扫描将从数值数据库列扫描的所有数字都字符串化为* string时,将检查对数值类型的扫描是否溢出. 例如,尽管float64(255)或" 255"可以扫描到uint8,但是值300的float64或值" 300"的字符串可以扫描到uint16,但不能扫描到uint8. 一个例外是,将一些float64数字扫描为字符串可能会在字符串化时丢失信息. 通常,将浮点列扫描到* float64中.

如果dest参数的类型为* [] byte,则Scan在该参数中保存相应数据的副本. 该副本归调用方所有,可以无限期修改和保存. 可以通过使用* RawBytes类型的参数来避免复制. 有关其使用限制,请参见RawBytes文档.

如果参数的类型为* interface {},则Scan会复制基础驱动程序提供的值而无需进行转换. 从[] byte类型的源值扫描到* interface {}时,将生成切片的副本,并且调用者拥有结果.

可以将类型为time.Time的源值扫描为* time.Time,* interface {},* string或* [] byte类型的值. 转换为后两者时,将使用time.RFC3339Nano.

布尔类型的源值可以扫描为* bool,* interface {},* string,* [] byte或* RawBytes类型.

For scanning into *bool, the source may be true, false, 1, 0, or string inputs parseable by strconv.ParseBool.

扫描还可以将查询返回的游标(例如"从双精度选择游标(从my_table中选择*)")转换为* Rows值,该值可以从中进行扫描. 如果父* Rows已关闭,则父选择查询将关闭所有游标* Rows.

type Scanner

扫描仪是扫描使用的界面.

type Scanner interface {
    // Scan assigns a value from a database driver.
    //
    // The src value will be of one of the following types:
    //
    //    int64
    //    float64
    //    bool
    //    []byte
    //    string
    //    time.Time
    //    nil - for NULL values
    //
    // An error should be returned if the value cannot be stored
    // without loss of information.
    //
    // Reference types such as []byte are only valid until the next call to Scan
    // and should not be retained. Their underlying memory is owned by the driver.
    // If retention is necessary, copy their values before the next call to Scan.
    Scan(src interface{}) error
}

type Stmt

Stmt是一个准备好的语句. 一个Stmt可安全地供多个goroutine并发使用.

如果在Tx或Conn上准备了Stmt,它将永远绑定到单个基础连接. 如果Tx或Conn关闭,则Stmt将变得不可用,并且所有操作都将返回错误. 如果在数据库上准备了Stmt,它将在数据库的整个生命周期内保持可用状态. 当Stmt需要在新的基础连接上执行时,它将自动在新的连接上进行准备.

type Stmt struct {
    // contains filtered or unexported fields
}

Example

func (*Stmt) Close

func (s *Stmt) Close() error

Close关闭语句.

func (*Stmt) Exec

func (s *Stmt) Exec(args ...interface{}) (Result, error)

Exec用给定的参数执行一个准备好的语句,并返回一个总结该语句效果的结果.

func (*Stmt) ExecContext 1.8

func (s *Stmt) ExecContext(ctx context.Context, args ...interface{}) (Result, error)

ExecContext用给定的参数执行一条准备好的语句,并返回一个总结语句效果的结果.

func (*Stmt) Query

func (s *Stmt) Query(args ...interface{}) (*Rows, error)

Query使用给定的参数执行准备好的查询语句,并将查询结果作为* Rows返回.

func (*Stmt) QueryContext 1.8

func (s *Stmt) QueryContext(ctx context.Context, args ...interface{}) (*Rows, error)

QueryContext executes a prepared query statement with the given arguments and returns the query results as a *Rows.

func (*Stmt) QueryRow

func (s *Stmt) QueryRow(args ...interface{}) *Row

QueryRow使用给定的参数执行准备好的查询语句. 如果在执行语句期间发生错误,则该错误将通过在返回的* Row上调用Scan来返回,该行始终为nil. 如果查询未选择任何行,则"行扫描"将返回ErrNoRows. 否则,*行扫描将扫描所选的第一行,并丢弃其余的行.

用法示例:

var name string
err := nameByUseridStmt.QueryRow(id).Scan(&name)

func (*Stmt) QueryRowContext 1.8

func (s *Stmt) QueryRowContext(ctx context.Context, args ...interface{}) *Row

QueryRowContext使用给定的参数执行准备好的查询语句. 如果在执行语句期间发生错误,则该错误将通过在返回的* Row上调用Scan来返回,该行始终为nil. 如果查询未选择任何行,则"行扫描"将返回ErrNoRows. 否则,*行扫描将扫描所选的第一行,并丢弃其余的行.

Example

type Tx

Tx是正在进行的数据库事务.

事务必须以调用Commit或Rollback结束.

调用Commit或Rollback后,事务上的所有操作均因ErrTxDone失败.

通过调用Commit或Rollback关闭通过调用事务的Prepare或Stmt方法为事务准备的语句.

type Tx struct {
    // contains filtered or unexported fields
}

func (*Tx) Commit

func (tx *Tx) Commit() error

提交提交事务.

func (*Tx) Exec

func (tx *Tx) Exec(query string, args ...interface{}) (Result, error)

Exec执行不返回行的查询. 例如:INSERT和UPDATE.

func (*Tx) ExecContext 1.8

func (tx *Tx) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error)

ExecContext执行不返回行的查询. 例如:INSERT和UPDATE.

Example

func (*Tx) Prepare

func (tx *Tx) Prepare(query string) (*Stmt, error)

Prepare creates a prepared statement for use within a transaction.

返回的语句在事务内运行,并且一旦事务已提交或回滚就不能再使用.

要在此事务上使用现有的准备好的语句,请参见Tx.Stmt.

Example

func (*Tx) PrepareContext 1.8

func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error)

PrepareContext创建一个准备好的语句以在事务中使用.

返回的语句在事务内运行,并且在事务已提交或回滚时将关闭.

要在此事务上使用现有的准备好的语句,请参见Tx.Stmt.

提供的上下文将用于上下文的准备,而不是用于执行返回的语句. 返回的语句将在事务上下文中运行.

func (*Tx) Query

func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error)

查询执行返回行的查询,通常为SELECT.

func (*Tx) QueryContext 1.8

func (tx *Tx) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error)

QueryContext执行一个查询,该查询返回行,通常是SELECT.

func (*Tx) QueryRow

func (tx *Tx) QueryRow(query string, args ...interface{}) *Row

QueryRow执行的查询预期最多返回一行. QueryRow始终返回非nil值. 错误将延迟到调用Row的Scan方法之前. 如果查询未选择任何行,则"行扫描"将返回ErrNoRows. 否则,*行扫描将扫描所选的第一行,并丢弃其余的行.

func (*Tx) QueryRowContext 1.8

func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row

QueryRowContext执行的查询预期最多返回一行. QueryRowContext始终返回非nil值. 错误将延迟到调用Row的Scan方法之前. 如果查询未选择任何行,则"行扫描"将返回ErrNoRows. 否则,*行扫描将扫描所选的第一行,并丢弃其余的行.

func (*Tx) Rollback

func (tx *Tx) Rollback() error

回滚将中止事务.

Example

func (*Tx) Stmt

func (tx *Tx) Stmt(stmt *Stmt) *Stmt

Stmt从现有语句返回特定于事务的预准备语句.

Example:

updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")
...
tx, err := db.Begin()
...
res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203)

返回的语句在事务内运行,并且在事务已提交或回滚时将关闭.

func (*Tx) StmtContext 1.8

func (tx *Tx) StmtContext(ctx context.Context, stmt *Stmt) *Stmt

StmtContext从现有语句返回特定于事务的预准备语句.

Example:

updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")
...
tx, err := db.Begin()
...
res, err := tx.StmtContext(ctx, updateMoney).Exec(123.45, 98293203)

提供的上下文用于语句的准备,而不是语句的执行.

返回的语句在事务内运行,并且在事务已提交或回滚时将关闭.

type TxOptions 1.8

TxOptions保留要在DB.BeginTx中使用的事务选项.

type TxOptions struct {
    // Isolation is the transaction isolation level.
    // If zero, the driver or database's default level is used.
    Isolation IsolationLevel
    ReadOnly  bool
}

Subdirectories

Name Synopsis
..
driver 程序包驱动程序定义了由程序包sql使用的数据库驱动程序要实现的接口.

by  ICOPY.SITE