Golang标准库——database

  • sql
  • sql/driver

sql

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

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

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

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 {
    // Atomic access only. At top of struct to prevent mis-alignment
    // on 32-bit platforms. Of type time.Duration.
    waitDuration int64 // Total time waited for new connections.

    connector driver.Connector
    // numClosed is an atomic counter which represents a total number of
    // closed connections. Stmt.openStmt checks it before cleaning closed
    // connections in Stmt.css.
    numClosed uint64

    mu           sync.Mutex // protects following fields
    freeConn     []*driverConn
    connRequests map[uint64]chan connRequest
    nextRequest  uint64 // Next key to use in connRequests.
    numOpen      int    // number of opened and pending open connections
    // Used to signal the need for new connections
    // a goroutine running connectionOpener() reads on this chan and
    // maybeOpenNewConnections sends on the chan (one send per needed connection)
    // It is closed during db.Close(). The close tells the connectionOpener
    // goroutine to exit.
    openerCh          chan struct{}
    closed            bool
    dep               map[finalCloser]depSet
    lastPut           map[*driverConn]string // stacktrace of last conn's put; debug only
    maxIdleCount      int                    // zero means defaultMaxIdleConns; negative means 0
    maxOpen           int                    // <= 0 means unlimited
    maxLifetime       time.Duration          // maximum amount of time a connection may be reused
    maxIdleTime       time.Duration          // maximum amount of time a connection may be idle before being closed
    cleanerCh         chan struct{}
    waitCount         int64 // Total number of connections waited for.
    maxIdleClosed     int64 // Total number of connections closed due to idle count.
    maxIdleTimeClosed int64 // Total number of connections closed due to idle time.
    maxLifetimeClosed int64 // Total number of connections closed due to max connection lifetime limit.

    stop func() // stop cancels the connection opener and the session resetter.
}

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 init() {
    sql.Register("mysql", &MySQLDriver{})
}

func newPool() *sql.DB {
    cfg := mysql.NewConfig()
    cfg.User = "root"
    cfg.Passwd = "xxxxxx"
    cfg.Net = "tcp"
    cfg.Addr = "127.0.0.1:3306"
    cfg.DBName = "mydb"
    dsn := cfg.FormatDSN()

    db, err := sql.Open("mysql", dsn)
    if err != nil {
        log.Fatal(err)
    }
    if err := db.Ping(); err != nil {
        log.Fatal(err)
    }
    return db
}

var pool = newPool()

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中的占位参数。

// InsertUser 插入用户
func InsertUser(name string) (int64, error) {
    res, err := pool.Exec("insert into `users` (`name`) values (?)", name)
    if err != nil {
        return 0, err
    }
    return res.LastInsertId()
}

// UpdateUser 更新用户
func UpdateUser(id int64, name string) error {
    _, err := pool.Exec("update `users` set `name` = ? where `id` = ?", name, id)
    if err != nil {
        return err
    }
    return nil
}

// DeleteUser 删除用户
func DeleteUser(id int64) error {
    _, err := pool.Exec("delete from `users` where `id` = ?", id)
    if err != nil {
        return err
    }
    return nil
}

func (*DB) Query

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

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

// User 用户
type User struct {
    ID   int64
    Name string
}

// QueryUser 根据id查询用户
// 注意:如果结果集为空集,这个代码是有问题的
func QueryUser(id int64) (*User, error) {
    rows, err := pool.Query("select `id`, `name` from `users` where `id` = ?", id)
    if err != nil {
        return nil, err
    }
    defer rows.Close() // 注意这里,一定要关闭
    user := User{}
    for rows.Next() {
        if err := rows.Scan(&user.ID, &user.Name); err != nil {
            return nil, err
        }
        break
    }
    if err := rows.Err(); err != nil {
        return nil, err
    }
    return &user, nil
}

func (*DB) QueryRow

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

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

// QueryUser1 单行查询
func QueryUser1(id int64) (*User, error) {
    row := pool.QueryRow("select `id`, `name` from `users` where `id` = ?", id)
    user := User{}
    if err := row.Scan(&user.ID, &user.Name); err != nil {
        if err == sql.ErrNoRows {
            return nil, nil  // 返回 (*User)(nil) 表示查询结果不错在
        }
        return nil, err
    }
    return &user, nil
}

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 {
    // One of these two will be non-nil:
    err  error // deferred error for easy chaining
    rows *Rows
}

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

func (*Row) Scan

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

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

type Rows

type Rows struct {
    dc          *driverConn // owned; must call releaseConn when closed to release
    releaseConn func(error)
    rowsi       driver.Rows
    cancel      func()      // called when Rows is closed, may be nil.
    closeStmt   *driverStmt // if non-nil, statement to Close on close

    // closemu prevents Rows from closing while there
    // is an active streaming result. It is held for read during non-close operations
    // and exclusively during close.
    //
    // closemu guards lasterr and closed.
    closemu sync.RWMutex
    closed  bool
    lasterr error // non-nil only if closed is true

    // lastcols is only used in Scan, Next, and NextResultSet which are expected
    // not to be called concurrently.
    lastcols []driver.Value
}

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 {
    // Immutable:
    db        *DB    // where we came from
    query     string // that created the Stmt
    stickyErr error  // if non-nil, this error is returned for all operations

    closemu sync.RWMutex // held exclusively during close, for read otherwise.

    // If Stmt is prepared on a Tx or Conn then cg is present and will
    // only ever grab a connection from cg.
    // If cg is nil then the Stmt must grab an arbitrary connection
    // from db and determine if it must prepare the stmt again by
    // inspecting css.
    cg   stmtConnGrabber
    cgds *driverStmt

    // parentStmt is set when a transaction-specific statement
    // is requested from an identical statement prepared on the same
    // conn. parentStmt is used to track the dependency of this statement
    // on its originating ("parent") statement so that parentStmt may
    // be closed by the user without them having to know whether or not
    // any transactions are still using it.
    parentStmt *Stmt

    mu     sync.Mutex // protects the rest of the fields
    closed bool

    // css is a list of underlying driver statement interfaces
    // that are valid on particular connections. This is only
    // used if cg == nil and one is found that has idle
    // connections. If cg != nil, cgds is always used.
    css []connStmt

    // lastNumClosed is copied from db.numClosed when Stmt is created
    // without tx and closed connections in css are removed.
    lastNumClosed uint64
}

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 {
    db *DB

    // closemu prevents the transaction from closing while there
    // is an active query. It is held for read during queries
    // and exclusively during close.
    closemu sync.RWMutex

    // dc is owned exclusively until Commit or Rollback, at which point
    // it's returned with putConn.
    dc  *driverConn
    txi driver.Tx

    // releaseConn is called once the Tx is closed to release
    // any held driverConn back to the pool.
    releaseConn func(error)

    // done transitions from 0 to 1 exactly once, on Commit
    // or Rollback. once done, all operations fail with
    // ErrTxDone.
    // Use atomic operations on value when checking value.
    done int32

    // keepConnOnRollback is true if the driver knows
    // how to reset the connection's session and if need be discard
    // the connection.
    keepConnOnRollback bool

    // All Stmts prepared for this transaction. These will be closed after the
    // transaction has been committed or rolled back.
    stmts struct {
        sync.Mutex
        v []*Stmt
    }

    // cancel is called after done transitions from 0 to 1.
    cancel func()

    // ctx lives for the life of the transaction.
    ctx context.Context
}

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放弃并回滚事务。

// UpdateFooBar 更新
func UpdateFooBar(id int64, x, y string) (err error) {
    tx, err := pool.Begin()
    if err != nil {
        return
    }
    defer func() {
        switch {
        case err != nil:
            tx.Rollback()
        default:
            err = tx.Commit()
        }
    }()

    _, err = tx.Exec("update `foo` set `x` = ? where `id` = ?", x, id)
    if err != nil {
        return
    }
    _, err = tx.Exec("update `bar` set `y` = ? where `id` = ?", y, id)
    if err != nil {
        return
    }

    return
}

database/sql/driver

driver包定义了应被数据库驱动实现的接口,这些接口会被sql包使用。

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

Variables

var Bool boolType

Bool是ValueConverter接口值,用于将输入的值转换为布尔类型。

转换规则如下:

- 布尔类型:不做修改
- 整数类型:
     1 为真
     0 为假
     其余整数会导致错误
- 字符串和[]byte:与strconv.ParseBool的规则相同
- 所有其他类型都会导致错误
var Int32 int32Type

Int32是一个ValueConverter接口值,用于将值转换为int64类型,会尊重int32类型的限制。

var String stringType

String是一个ValueConverter接口值,用于将值转换为字符串。如果值v是字符串或者[]byte类型,不会做修改,如果值v是其它类型,会转换为fmt.Sprintf("%v", v)。

var DefaultParameterConverter defaultConverter

DefaultParameterConverter是ValueConverter接口的默认实现,当一个Stmt没有实现ColumnConverter时,就会使用它。

如果值value满足函数IsValue(value)为真,DefaultParameterConverter直接返回 value。否则,整数类型会被转换为int64,浮点数转换为float64,字符串转换为[]byte。其它类型会导致错误。

var ResultNoRows noRows

ResultNoRows是预定义的Result类型值,用于当一个DDL命令(如create table)成功时被驱动返回。它的LastInsertId和RowsAffected方法都返回错误。

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

ErrBadConn应被驱动返回,以通知sql包一个driver.Conn处于损坏状态(如服务端之前关闭了连接),sql包会重启一个新的连接。

为了避免重复的操作,如果数据库服务端执行了操作,就不应返回ErrBadConn。即使服务端返回了一个错误。

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

ErrSkip可能会被某些可选接口的方法返回,用于在运行时表明快速方法不可用,sql包应像未实现该接口的情况一样执行。ErrSkip只有文档显式说明的地方才支持。

type Value

type Value interface{}

Value是驱动必须能处理的值。它要么是nil,要么是如下类型的实例:

int64
float64
bool
[]byte
string   [*] Rows.Next不会返回该类型值
time.Time

type Valuer

type Valuer interface {
    // Value返回一个驱动支持的Value类型值
    Value() (Value, error)
}

Valuer是提供Value方法的接口。实现了Valuer接口的类型可以将自身转换为驱动支持的Value类型值。

func IsValue

func IsValue(v interface{}) bool

IsValue报告v是否是合法的Value类型参数。和IsScanValue不同,IsValue接受字符串类型。

func IsScanValue

func IsScanValue(v interface{}) bool

IsScanValue报告v是否是合法的Value扫描类型参数。和IsValue不同,IsScanValue不接受字符串类型。

type ValueConverter

type ValueConverter interface {
    // ConvertValue将一个值转换为驱动支持的Value类型
    ConvertValue(v interface{}) (Value, error)
}

ValueConverter接口提供了ConvertValue方法。

driver包提供了各种ValueConverter接口的实现,以保证不同驱动之间的实现和转换的一致性。ValueConverter接口有如下用途:

* 转换sql包提供的Value类型值到数据库指定列的类型,并保证它的匹配,
  例如保证某个int64值满足一个表的uint16列。

* 转换数据库提供的值到驱动的Value类型。

* 在扫描时被sql包用于将驱动的Value类型转换为用户的类型。

type ColumnConverter

type ColumnConverter interface {
    // ColumnConverter返回指定列的ValueConverter
    // 如果该列未指定类型,或不应特殊处理,应返回DefaultValueConverter
    ColumnConverter(idx int) ValueConverter
}

如果Stmt有自己的列类型,可以实现ColumnConverter接口,返回值可以将任意类型转换为驱动的Value类型。

type NotNull

type NotNull struct {
    Converter ValueConverter
}

NotNull实现了ValueConverter接口,不允许nil值,否则会将值交给Converter字段处理。

func (NotNull) ConvertValue

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

type Null

type Null struct {
    Converter ValueConverter
}

Null实现了ValueConverter接口,允许nil值,否则会将值交给Converter字段处理。

func (Null) ConvertValue

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

type Driver

type Driver interface {
    // Open返回一个新的与数据库的连接,参数name的格式是驱动特定的。
    //
    // Open可能返回一个缓存的连接(之前关闭的连接),但这么做是不必要的;
    // sql包会维护闲置连接池以便有效的重用连接。
    //
    // 返回的连接同一时间只会被一个go程使用。
    Open(name string) (Conn, error)
}

Driver接口必须被数据库驱动实现。

type Conn

type Conn interface {
    // Prepare返回一个准备好的、绑定到该连接的状态。
    Prepare(query string) (Stmt, error)

    // Close作废并停止任何现在准备好的状态和事务,将该连接标注为不再使用。
    //
    // 因为sql包维护着一个连接池,只有当闲置连接过剩时才会调用Close方法,
    // 驱动的实现中不需要添加自己的连接缓存池。
    Close() error

    // Begin开始并返回一个新的事务。
    Begin() (Tx, error)
}

Conn是与数据库的连接。该连接不会被多线程并行使用。连接被假定为具有状态的。

type Execer

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

Execer是一个可选的、可能被Conn接口实现的接口。

如果一个Conn未实现Execer接口,sql包的DB.Exec会首先准备一个查询,执行状态,然后关闭状态。Exec可能会返回ErrSkip。

type Queryer

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

Queryer是一个可选的、可能被Conn接口实现的接口。

如果一个Conn未实现Queryer接口,sql包的DB.Query会首先准备一个查询,执行状态,然后关闭状态。Query可能会返回ErrSkip。

type Stmt

type Stmt interface {
    // Close关闭Stmt。
    //
    // 和Go1.1一样,如果Stmt被任何查询使用中的话,将不会被关闭。
    Close() error

    // NumInput返回占位参数的个数。
    //
    // 如果NumInput返回值 >= 0,sql包会提前检查调用者提供的参数个数,
    // 并且会在调用Exec或Query方法前返回数目不对的错误。
    //
    // NumInput可以返回-1,如果驱动占位参数的数量。
    // 此时sql包不会提前检查参数个数。
    NumInput() int

    // Exec执行查询,而不会返回结果,如insert或update。
    Exec(args []Value) (Result, error)

    // Query执行查询并返回结果,如select。
    Query(args []Value) (Rows, error)
}

Stmt是准备好的状态。它会绑定到一个连接,不应被多go程同时使用。

type Tx

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

Tx是一次事务。

type Result

type Result interface {
    // LastInsertId返回insert等命令后数据库自动生成的ID
    LastInsertId() (int64, error)

    // RowsAffected返回被查询影响的行数
    RowsAffected() (int64, error)
}

Result是查询执行的结果。

type RowsAffected

type RowsAffected int64

RowsAffected实现了Result接口,用于insert或update操作,这些操作会修改零到多行数据。

func (RowsAffected) LastInsertId

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

func (RowsAffected) RowsAffected

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

type Rows

type Rows interface {
    // Columns返回各列的名称,列的数量可以从切片长度确定。
    // 如果某个列的名称未知,对应的条目应为空字符串。
    Columns() []string

    // Close关闭Rows。
    Close() error

    // 调用Next方法以将下一行数据填充进提供的切片中。
    // 提供的切片必须和Columns返回的切片长度相同。
    //
    // 切片dest可能被填充同一种驱动Value类型,但字符串除外。
    // 所有string值都必须转换为[]byte。
    //
    // 当没有更多行时,Next应返回io.EOF。
    Next(dest []Value) error
}

Rows是执行查询得到的结果的迭代器。

你可能感兴趣的:(Golang标准库——database)