package sql

import "database/sql"

sql包提供了保证SQL或类SQL数据库的泛用接口。

使用sql包时必须注入(至少)一个数据库驱动。参见http://golang.org/s/sqldrivers 获取驱动列表。

更多用法示例,参见wiki页面:http://golang.org/s/sqlwiki

Index

返回首页


  • Variables
  • type Scanner
  • type NullBool
  • type NullInt64
  • type NullFloat64
  • type NullString
  • type RawBytes
  • type Result
  • type DB
  • type Row
  • type Rows
  • type Stmt
  • type Tx
  • func Register(name string, driver driver.Driver)
  • Examples

    返回首页


  • DB.Query
  • DB.QueryRow
  • Variables

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

    当QueryRow方法没有返回一个row时,调用返回值的Scan方法会返回ErrNoRows。此时,QueryRow返回一个占位的*Row值,延迟本错误直到调用Scan方法时才释放。

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

    func Register

    func Register(name string, driver driver.Driver)

    Register注册并命名一个数据库,可以在Open函数中使用该命名启用该驱动。如果 Register注册同一名称两次,或者driver参数为nil,会导致panic。

    type Scanner

    type Scanner interface {
        // Scan方法从数据库驱动获取一个值。
        //
        // 参数src的类型保证为如下类型之一:
        //
        //    int64
        //    float64
        //    bool
        //    []byte
        //    string
        //    time.Time
        //    nil - 表示NULL值
        //
        // 如果不能不丢失信息的保存一个值,应返回错误。
        Scan(src interface{}) error
    }

    Scanner接口会被Rows或Row的Scan方法使用。

    type NullBool

    type NullBool struct {
        Bool  bool
        Valid bool // 如果Bool不是NULL则Valid为真
    }

    NullBool代表一个可为NULL的布尔值。NullBool实现了Scanner接口,因此可以作为Rows/Row的Scan方法的参数保存扫描结果,类似NullString。

    func (*NullBool) Scan

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

    Scan实现了Scanner接口。

    func (NullBool) Value

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

    Value实现了driver.Valuer接口。

    type NullInt64

    type NullInt64 struct {
        Int64 int64
        Valid bool // 如果Int64不是NULL则Valid为真
    }

    NullInt64代表一个可为NULL的int64值。NullInt64实现了Scanner接口,因此可以作为Rows/Row的Scan方法的参数保存扫描结果,类似NullString。

    func (*NullInt64) Scan

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

    Scan实现了Scanner接口。

    func (NullInt64) Value

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

    Value实现了driver.Valuer接口。

    type NullFloat64

    type NullFloat64 struct {
        Float64 float64
        Valid   bool // 如果Float64不是NULL则Valid为真
    }

    NullFloat64代表一个可为NULL的float64值。NullFloat64实现了Scanner接口,因此可以作为Rows/Row的Scan方法的参数保存扫描结果,类似NullString。

    func (*NullFloat64) Scan

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

    Scan实现了Scanner接口。

    func (NullFloat64) Value

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

    Value实现了driver.Valuer接口。

    type NullString

    type NullString struct {
        String string
        Valid  bool // 如果String不是NULL则Valid为真
    }

    NullString代表一个可为NULL的字符串。NullString实现了Scanner接口,因此可以作为Rows/Row的Scan方法的参数保存扫描结果:

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

    func (*NullString) Scan

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

    Scan实现了Scanner接口。

    func (NullString) Value

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

    Value实现了driver.Valuer接口。

    type RawBytes

    type RawBytes []byte

    RawBytes是一个字节切片,保管对内存的引用,为数据库自身所使用。在Scaner接口的Scan方法写入RawBytes数据后,该切片只在限次调用Next、Scan或Close方法之前合法。

    type Result

    type Result interface {
        // LastInsertId返回一个数据库生成的回应命令的整数。
        // 当插入新行时,一般来自一个"自增"列。
        // 不是所有的数据库都支持该功能,该状态的语法也各有不同。
        LastInsertId() (int64, error)
    
        // RowsAffected返回被update、insert或delete命令影响的行数。
        // 不是所有的数据库都支持该功能。
        RowsAffected() (int64, error)
    }

    Result是对已执行的SQL命令的总结。

    type DB

    type DB struct {
        // 内含隐藏或非导出字段
    }

    DB是一个数据库(操作)句柄,代表一个具有零到多个底层连接的连接池。它可以安全的被多个go程同时使用。

    sql包会自动创建和释放连接;它也会维护一个闲置连接的连接池。如果数据库具有单连接状态的概念,该状态只有在事务中被观察时才可信。一旦调用了BD.Begin,返回的Tx会绑定到单个连接。当调用事务Tx的Commit或Rollback后,该事务使用的连接会归还到DB的闲置连接池中。连接池的大小可以用SetMaxIdleConns方法控制。

    func Open

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

    Open打开一个dirverName指定的数据库,dataSourceName指定数据源,一般包至少括数据库文件名和(可能的)连接信息。

    大多数用户会通过数据库特定的连接帮助函数打开数据库,返回一个*DB。Go标准库中没有数据库驱动。参见http://golang.org/s/sqldrivers获取第三方驱动。

    Open函数可能只是验证其参数,而不创建与数据库的连接。如果要检查数据源的名称是否合法,应调用返回值的Ping方法。

    返回的DB可以安全的被多个go程同时使用,并会维护自身的闲置连接池。这样一来,Open函数只需调用一次。很少需要关闭DB。

    func (*DB) Driver

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

    Driver方法返回数据库下层驱动。

    func (*DB) Ping

    func (db *DB) Ping() error

    Ping检查与数据库的连接是否仍有效,如果需要会创建连接。

    func (*DB) Close

    func (db *DB) Close() error

    Close关闭数据库,释放任何打开的资源。一般不会关闭DB,因为DB句柄通常被多个go程共享,并长期活跃。

    func (*DB) SetMaxOpenConns

    func (db *DB) SetMaxOpenConns(n int)

    SetMaxOpenConns设置与数据库建立连接的最大数目。

    如果n大于0且小于最大闲置连接数,会将最大闲置连接数减小到匹配最大开启连接数的限制。

    如果n <= 0,不会限制最大开启连接数,默认为0(无限制)。

    func (*DB) SetMaxIdleConns

    func (db *DB) SetMaxIdleConns(n int)

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

    如果n大于最大开启连接数,则新的最大闲置连接数会减小到匹配最大开启连接数的限制。

    如果n <= 0,不会保留闲置连接。

    func (*DB) Exec

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

    Exec执行一次命令(包括查询、删除、更新、插入等),不返回任何执行结果。参数args表示query中的占位参数。

    func (*DB) Query

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

    Query执行一次查询,返回多行结果(即Rows),一般用于执行select命令。参数args表示query中的占位参数。

    Example
    age := 27
    rows, err := db.Query("SELECT name FROM users WHERE age=?", age)
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()
    for rows.Next() {
        var name string
        if err := rows.Scan(&name); err != nil {
            log.Fatal(err)
        }
        fmt.Printf("%s is %d\n", name, age)
    }
    if err := rows.Err(); err != nil {
        log.Fatal(err)
    }
    

    func (*DB) QueryRow

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

    QueryRow执行一次查询,并期望返回最多一行结果(即Row)。QueryRow总是返回非nil的值,直到返回值的Scan方法被调用时,才会返回被延迟的错误。(如:未找到结果)

    Example
    id := 123
    var username string
    err := db.QueryRow("SELECT username FROM users WHERE id=?", id).Scan(&username)
    switch {
    case err == sql.ErrNoRows:
        log.Printf("No user with that ID.")
    case err != nil:
        log.Fatal(err)
    default:
        fmt.Printf("Username is %s\n", username)
    }
    

    func (*DB) Prepare

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

    Prepare创建一个准备好的状态用于之后的查询和命令。返回值可以同时执行多个查询和命令。

    func (*DB) Begin

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

    Begin开始一个事务。隔离水平由数据库驱动决定。

    type Row

    type Row struct {
        // 内含隐藏或非导出字段
    }

    QueryRow方法返回Row,代表单行查询结果。

    func (*Row) Scan

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

    Scan将该行查询结果各列分别保存进dest参数指定的值中。如果该查询匹配多行,Scan会使用第一行结果并丢弃其余各行。如果没有匹配查询的行,Scan会返回ErrNoRows。

    type Rows

    type Rows struct {
        // 内含隐藏或非导出字段
    }

    Rows是查询的结果。它的游标指向结果集的第零行,使用Next方法来遍历各行结果:

    rows, err := db.Query("SELECT ...")
    ...
    defer rows.Close()
    for rows.Next() {
        var id int
        var name string
        err = rows.Scan(&id, &name)
        ...
    }
    err = rows.Err() // get any error encountered during iteration
    ...

    func (*Rows) Columns

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

    Columns返回列名。如果Rows已经关闭会返回错误。

    func (*Rows) Scan

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

    Scan将当前行各列结果填充进dest指定的各个值中。

    如果某个参数的类型为*[]byte,Scan会保存对应数据的拷贝,该拷贝为调用者所有,可以安全的,修改或无限期的保存。如果参数类型为*RawBytes可以避免拷贝;参见RawBytes的文档获取其使用的约束。

    如果某个参数的类型为*interface{},Scan会不做转换的拷贝底层驱动提供的值。如果值的类型为[]byte,会进行数据的拷贝,调用者可以安全使用该值。

    func (*Rows) Next

    func (rs *Rows) Next() bool

    Next准备用于Scan方法的下一行结果。如果成功会返回真,如果没有下一行或者出现错误会返回假。Err应该被调用以区分这两种情况。

    每一次调用Scan方法,甚至包括第一次调用该方法,都必须在前面先调用Next方法。

    func (*Rows) Close

    func (rs *Rows) Close() error

    Close关闭Rows,阻止对其更多的列举。 如果Next方法返回假,Rows会自动关闭,满足。检查Err方法结果的条件。Close方法时幂等的(多次调用无效的成功),不影响Err方法的结果。

    func (*Rows) Err

    func (rs *Rows) Err() error

    Err返回可能的、在迭代时出现的错误。Err需在显式或隐式调用Close方法后调用。

    type Stmt

    type Stmt struct {
        // 内含隐藏或非导出字段
    }

    Stmt是准备好的状态。Stmt可以安全的被多个go程同时使用。

    func (*Stmt) Exec

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

    Exec使用提供的参数执行准备好的命令状态,返回Result类型的该状态执行结果的总结。

    func (*Stmt) Query

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

    Query使用提供的参数执行准备好的查询状态,返回Rows类型查询结果。

    func (*Stmt) QueryRow

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

    QueryRow使用提供的参数执行准备好的查询状态。如果在执行时遇到了错误,该错误会被延迟,直到返回值的Scan方法被调用时才释放。返回值总是非nil的。如果没有查询到结果,*Row类型返回值的Scan方法会返回ErrNoRows;否则,Scan方法会扫描结果第一行并丢弃其余行。

    示例用法:

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

    func (*Stmt) Close

    func (s *Stmt) Close() error

    Close关闭状态。

    type Tx

    type Tx struct {
        // 内含隐藏或非导出字段
    }

    Tx代表一个进行中的数据库事务。

    一次事务必须以对Commit或Rollback的调用结束。

    调用Commit或Rollback后,所有对事务的操作都会失败并返回错误值ErrTxDone。

    func (*Tx) Exec

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

    Exec执行命令,但不返回结果。例如执行insert和update。

    func (*Tx) Query

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

    Query执行查询并返回零到多行结果(Rows),一般执行select命令。

    func (*Tx) QueryRow

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

    QueryRow执行查询并期望返回最多一行结果(Row)。QueryRow总是返回非nil的结果,查询失败的错误会延迟到在调用该结果的Scan方法时释放。

    func (*Tx) Prepare

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

    Prepare准备一个专用于该事务的状态。返回的该事务专属状态操作在Tx递交会回滚后不能再使用。要在该事务中使用已存在的状态,参见Tx.Stmt方法。

    func (*Tx) Stmt

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

    Stmt使用已存在的状态生成一个该事务特定的状态。

    示例:

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

    func (tx *Tx) Commit() error

    Commit递交事务。

    func (*Tx) Rollback

    func (tx *Tx) Rollback() error

    Rollback放弃并回滚事务。