...

Package sql

import "database/sql"
概览
索引
示例
子目录

概览 ▾

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

sql 包必须与数据库驱动结合使用。驱动列表见 http://golang.org/s/sqldrivers

更多使用范例见 http://golang.org/s/sqlwiki 的维基页面。

索引 ▾

变量
func Drivers() []string
func Register(name string, driver driver.Driver)
type DB
    func Open(driverName, dataSourceName string) (*DB, error)
    func (db *DB) Begin() (*Tx, error)
    func (db *DB) Close() error
    func (db *DB) Driver() driver.Driver
    func (db *DB) Exec(query string, args ...interface{}) (Result, error)
    func (db *DB) Ping() error
    func (db *DB) Prepare(query string) (*Stmt, error)
    func (db *DB) Query(query string, args ...interface{}) (*Rows, error)
    func (db *DB) QueryRow(query string, args ...interface{}) *Row
    func (db *DB) SetMaxIdleConns(n int)
    func (db *DB) SetMaxOpenConns(n int)
    func (db *DB) Stats() DBStats
type DBStats
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 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 RawBytes
type Result
type Row
    func (r *Row) Scan(dest ...interface{}) error
type Rows
    func (rs *Rows) Close() error
    func (rs *Rows) Columns() ([]string, error)
    func (rs *Rows) Err() error
    func (rs *Rows) Next() 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) Query(args ...interface{}) (*Rows, error)
    func (s *Stmt) QueryRow(args ...interface{}) *Row
type Tx
    func (tx *Tx) Commit() error
    func (tx *Tx) Exec(query string, args ...interface{}) (Result, error)
    func (tx *Tx) Prepare(query string) (*Stmt, error)
    func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error)
    func (tx *Tx) QueryRow(query string, args ...interface{}) *Row
    func (tx *Tx) Rollback() error
    func (tx *Tx) Stmt(stmt *Stmt) *Stmt

包文件

convert.go sql.go

变量

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

ErrNoRows是QueryRow的时候,当没有返回任何数据,Scan会返回的错误。 在这种情况下,QueryRow会返回一个*Row的标示符,直到调用Scan的时候才返回这个error。

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

func Drivers

func Drivers() []string

Drivers returns a sorted list of the names of the registered drivers.

func Register

func Register(name string, driver driver.Driver)

Register使得数据库驱动可以使用事先定义好的名字使用。 如果使用同样的名字注册,或者是注册的的sql驱动是空的,Register会panic。

type DB

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

DB is a database handle representing a pool of zero or more underlying connections. It's safe for concurrent use by multiple goroutines.

The sql package creates and frees connections automatically; it also maintains a free pool of idle connections. If the database has a concept of per-connection state, such state can only be reliably observed within a transaction. Once DB.Begin is called, the returned Tx is bound to a single connection. Once Commit or Rollback is called on the transaction, that transaction's connection is returned to DB's idle connection pool. The pool size can be controlled with SetMaxIdleConns. TODO:待译

func Open

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

Open打开一个数据库,这个数据库是由其驱动名称和驱动制定的数据源信息打开的,这个数据源信息通常 是由至少一个数据库名字和连接信息组成的。

多数用户通过指定的驱动连接辅助函数来打开一个数据库。打开数据库之后会返回*DB。

TODO:待译

func (*DB) Begin

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

Begin开始一个事务。事务的隔离级别是由驱动决定的。

func (*DB) Close

func (db *DB) Close() error

Close关闭数据库,释放一些使用中的资源。 TODO: 待译

func (*DB) Driver

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

Driver返回了数据库的底层驱动。

func (*DB) Exec

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

Exec 执行query操作,而不返回任何行。 args 为查询中的任意占位符形参。

func (*DB) Ping

func (db *DB) Ping() error

Ping verifies a connection to the database is still alive, establishing a connection if necessary. TODO:待译

func (*DB) Prepare

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

Prepare 为以后的查询或执行操作事先创建了语句。 多个查询或执行操作可在返回的语句中并发地运行。

func (*DB) Query

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

Query执行了一个有返回行的查询操作,比如SELECT。 args 形参为该查询中的任何占位符。

示例

代码:

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执行一个至多只返回一行记录的查询操作。 QueryRow总是返回一个非空值。Error只会在调用行的Scan方法的时候才返回。

示例

代码:

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

func (db *DB) SetMaxIdleConns(n int)

SetMaxIdleConns sets the maximum number of connections in the idle connection pool.

If MaxOpenConns is greater than 0 but less than the new MaxIdleConns then the new MaxIdleConns will be reduced to match the MaxOpenConns limit

If n <= 0, no idle connections are retained. TODO:待译

func (*DB) SetMaxOpenConns

func (db *DB) SetMaxOpenConns(n int)

SetMaxOpenConns sets the maximum number of open connections to the database.

If MaxIdleConns is greater than 0 and the new MaxOpenConns is less than MaxIdleConns, then MaxIdleConns will be reduced to match the new MaxOpenConns limit

If n <= 0, then there is no limit on the number of open connections. The default is 0 (unlimited).

func (*DB) Stats

func (db *DB) Stats() DBStats

Stats returns database statistics.

type DBStats

type DBStats struct {
    // OpenConnections is the number of open connections to the database.
    OpenConnections int
}

DBStats contains database statistics.

type NullBool

type NullBool struct {
    Bool  bool
    Valid bool // Valid is true if Bool is not NULL  // 如果Bool非空,Valid就为true
}

NullBool代表了可空的bool类型。 NullBool实现了Scanner接口,所以它和NullString一样可以被当做scan的目标变量。

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 NullFloat64

type NullFloat64 struct {
    Float64 float64
    Valid   bool // Valid is true if Float64 is not NULL  // 如果Float64非空,Valid就为true。
}

NullFloat64代表了可空的float64类型。 NullFloat64实现了Scanner接口,所以它和NullString一样可以被当做scan的目标变量。

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 NullInt64

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

NullInt64代表了可空的int64类型。 NullInt64实现了Scanner接口,所以它和NullString一样可以被当做scan的目标变量。

func (*NullInt64) Scan

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

Scan实现了Scaner接口。

func (NullInt64) Value

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

Value实现了driver Valuer接口。

type NullString

type NullString struct {
    String string
    Valid  bool // Valid is true if String is not NULL  // 如果String不是空,则Valid为true
}

NullString代表一个可空的string。 NUllString实现了Scanner接口,所以它可以被当做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是一个字节数组,它是由数据库自己维护的一个内存空间。 当一个Scan被放入到RawBytes中之后,你下次调用Next,Scan或者Close就可以获取到slice了。

type Result

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

一个Result结构代表了一个执行过的SQL命令。

type Row

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

Row是调用QueryRow的结果,代表了查询操作的一行数据。

func (*Row) Scan

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

Scan将符合的行的对应列拷贝到dest指的对应值中。 如果多于一个的行满足查询条件,Scan使用第一行,而忽略其他行。 如果没有行满足查询条件,Scan返回ErrNoRows。

type Rows

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

Rows代表查询的结果。它的指针最初指向结果集的第一行数据,需要使用Next来进一步操作。

rows, err := db.Query("SELECT ...")
...
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) Close

func (rs *Rows) Close() error

Close 关闭 Rows,阻止了进一步枚举。若 Next 返回 false,则 Rows 会自动关闭并能够检查 Err 的结果。Close 是幂等的,并不会影响 Err 的结果。

func (*Rows) Columns

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

Columns返回列名字。 当rows设置了closed,Columns方法会返回error。

func (*Rows) Err

func (rs *Rows) Err() error

Err 返回错误。如果有错误的话,就会在循环过程中捕获到。 Err 可能会在一个显式或隐式的 Close 后调用。

func (*Rows) Next

func (rs *Rows) Next() bool

Next获取下一行的数据以便给Scan调用。 在成功的时候返回true,在没有下一行数据,或在准备过程中发生错误时返回false。 应通过 Err 来区分这两种情况。

每次调用来Scan获取数据,甚至是第一行数据,都需要调用Next来处理。

func (*Rows) Scan

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

Scan将当前行的列输出到dest指向的目标值中。

如果有个参数是*[]byte的类型,Scan在这个参数里面存放的是相关数据的拷贝。 这个拷贝是调用函数的人所拥有的,并且可以随时被修改和存取。这个拷贝能避免使用*RawBytes; 关于这个类型的使用限制请参考文档。

如果有个参数是*interface{}类型,Scan会将底层驱动提供的这个值不做任何转换直接拷贝返回。 如果值是[]byte类型,Scan就会返回一份拷贝,并且调用者获得返回结果。

type Scanner

type Scanner interface {

    // Scan从数据库驱动中设置一个值。
    //
    // src值可以是下面限定的集中类型之一:
    //
    //    int64
    //    float64
    //    bool
    //    []byte
    //    string
    //    time.Time
    //    nil - for NULL values
    //
    // 如果数据只有通过丢失信息才能存储下来,这个方法就会返回error。
    Scan(src interface{}) error
}

Scanner是被Scan使用的接口。

type Stmt

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

Stmt是定义好的声明。多个goroutine并发使用Stmt是安全的。

func (*Stmt) Close

func (s *Stmt) Close() error

关闭声明。

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根据传递的参数执行一个声明的查询操作。如果在执行声明过程中发生了错误, 这个error就会在Scan返回的*Row的时候返回,而这个*Row永远不会是nil。 如果查询没有任何行数据,*Row的Scan操作就会返回ErrNoRows。 否则,*Rows的Scan操作就会返回第一行数据,并且忽略其他行。

Example usage:

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

type Tx

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

Tx代表运行中的数据库事务。

必须调用Commit或者Rollback来结束事务。

在调用 Commit 或者 Rollback 之后,所有对事务的后续操作就会返回 ErrTxDone。

func (*Tx) Commit

func (tx *Tx) Commit() error

Commit提交事务。

func (*Tx) Exec

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

Exec执行不返回任何行的操作。 例如:INSERT和UPDATE操作。

func (*Tx) Prepare

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

Prepare在一个事务中定义了一个操作的声明。

这里定义的声明操作一旦事务被调用了commited或者rollback之后就不能使用了。

关于如何使用定义好的操作声明,请参考Tx.Stmt。

func (*Tx) Query

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

Query执行哪些返回行的查询操作,比如SELECT。

func (*Tx) QueryRow

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

QueryRow执行的查询至多返回一行数据。 QueryRow总是返回非空值。只有当执行行的Scan方法的时候,才会返回Error。

func (*Tx) Rollback

func (tx *Tx) Rollback() error

Rollback回滚事务。

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)

子目录

名称      摘要
..
driver      Package driver defines interfaces to be implemented by database drivers as used by package sql.