package sql
import "database/sql"
Package sql 提供了围绕 SQL(或类 SQL)数据库的通用接口。
sql 包必须与数据库驱动一起使用。 驱动列表见 https://golang.org/s/sqldrivers。
不支持 context 取消的驱动在查询完成之前不会返回。
用法示例见 wiki 页面 https://golang.org/s/sqlwiki。
Example (OpenDBCLI)
package main
import (
"context"
"database/sql"
"flag"
"log"
"os"
"os/signal"
"time"
)
var pool *sql.DB // Database connection pool.
func main() {
id := flag.Int64("id", 0, "person ID to find")
dsn := flag.String("dsn", os.Getenv("DSN"), "connection data source name")
flag.Parse()
if len(*dsn) == 0 {
log.Fatal("missing dsn flag")
}
if *id == 0 {
log.Fatal("missing person ID")
}
var err error
// Opening a driver typically will not attempt to connect to the database.
pool, err = sql.Open("driver-name", *dsn)
if err != nil {
// This will not be a connection error, but a DSN parse error or
// another initialization error.
log.Fatal("unable to use data source name", err)
}
defer pool.Close()
pool.SetConnMaxLifetime(0)
pool.SetMaxIdleConns(3)
pool.SetMaxOpenConns(3)
ctx, stop := context.WithCancel(context.Background())
defer stop()
appSignal := make(chan os.Signal, 3)
signal.Notify(appSignal, os.Interrupt)
go func() {
<-appSignal
stop()
}()
Ping(ctx)
Query(ctx, *id)
}
// Ping the database to verify DSN provided by the user is valid and the
// server accessible. If the ping fails exit the program with an error.
func Ping(ctx context.Context) {
ctx, cancel := context.WithTimeout(ctx, 1*time.Second)
defer cancel()
if err := pool.PingContext(ctx); err != nil {
log.Fatalf("unable to connect to database: %v", err)
}
}
// Query the database for the information requested and prints the results.
// If the query fails exit the program with an error.
func Query(ctx context.Context, id int64) {
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
var name string
err := pool.QueryRowContext(ctx, "select p.name from people as p where p.id = :id;", sql.Named("id", id)).Scan(&name)
if err != nil {
log.Fatal("unable to execute search query", err)
}
log.Println("name=", name)
}
Example (OpenDBService)
package main
import (
"context"
"database/sql"
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"time"
)
func main() {
// Opening a driver typically will not attempt to connect to the database.
db, err := sql.Open("driver-name", "database=test1")
if err != nil {
// This will not be a connection error, but a DSN parse error or
// another initialization error.
log.Fatal(err)
}
db.SetConnMaxLifetime(0)
db.SetMaxIdleConns(50)
db.SetMaxOpenConns(50)
s := &Service{db: db}
http.ListenAndServe(":8080", s)
}
type Service struct {
db *sql.DB
}
func (s *Service) ServeHTTP(w http.ResponseWriter, r *http.Request) {
db := s.db
switch r.URL.Path {
default:
http.Error(w, "not found", http.StatusNotFound)
return
case "/healthz":
ctx, cancel := context.WithTimeout(r.Context(), 1*time.Second)
defer cancel()
err := s.db.PingContext(ctx)
if err != nil {
http.Error(w, fmt.Sprintf("db down: %v", err), http.StatusFailedDependency)
return
}
w.WriteHeader(http.StatusOK)
return
case "/quick-action":
// This is a short SELECT. Use the request context as the base of
// the context timeout.
ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
defer cancel()
id := 5
org := 10
var name string
err := db.QueryRowContext(ctx, `
select
p.name
from
people as p
join organization as o on p.organization = o.id
where
p.id = :id
and o.id = :org
;`,
sql.Named("id", id),
sql.Named("org", org),
).Scan(&name)
if err != nil {
if err == sql.ErrNoRows {
http.Error(w, "not found", http.StatusNotFound)
return
}
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
io.WriteString(w, name)
return
case "/long-action":
// This is a long SELECT. Use the request context as the base of
// the context timeout, but give it some time to finish. If
// the client cancels before the query is done the query will also
// be canceled.
ctx, cancel := context.WithTimeout(r.Context(), 60*time.Second)
defer cancel()
var names []string
rows, err := db.QueryContext(ctx, "select p.name from people as p where p.active = true;")
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
for rows.Next() {
var name string
err = rows.Scan(&name)
if err != nil {
break
}
names = append(names, name)
}
// Check for errors during rows "Close".
// This may be more important if multiple statements are executed
// in a single batch and rows were written as well as read.
if closeErr := rows.Close(); closeErr != nil {
http.Error(w, closeErr.Error(), http.StatusInternalServerError)
return
}
// Check for row scan error.
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
// Check for errors during row iteration.
if err = rows.Err(); err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
json.NewEncoder(w).Encode(names)
return
case "/async-action":
// This action has side effects that we want to preserve
// even if the client cancels the HTTP request part way through.
// For this we do not use the http request context as a base for
// the timeout.
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
var orderRef = "ABC123"
tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable})
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
_, err = tx.ExecContext(ctx, "stored_proc_name", orderRef)
if err != nil {
tx.Rollback()
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
err = tx.Commit()
if err != nil {
http.Error(w, "action in unknown state, check state before attempting again", http.StatusInternalServerError)
return
}
w.WriteHeader(http.StatusOK)
return
}
}
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 ...any) (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 ...any) (*Rows, error)
- func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...any) *Row
- func (c *Conn) Raw(f func(driverConn any) 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 ...any) (Result, error)
- func (db *DB) ExecContext(ctx context.Context, query string, args ...any) (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 ...any) (*Rows, error)
- func (db *DB) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error)
- func (db *DB) QueryRow(query string, args ...any) *Row
- func (db *DB) QueryRowContext(ctx context.Context, query string, args ...any) *Row
- func (db *DB) SetConnMaxIdleTime(d time.Duration)
- 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
- type NamedArg
- type Null
- type NullBool
- type NullByte
- type NullFloat64
- type NullInt16
- type NullInt32
- type NullInt64
- type NullString
- type NullTime
- type Out
- type RawBytes
- type Result
- type Row
- type Rows
- type Scanner
-
type Stmt
- func (s *Stmt) Close() error
- func (s *Stmt) Exec(args ...any) (Result, error)
- func (s *Stmt) ExecContext(ctx context.Context, args ...any) (Result, error)
- func (s *Stmt) Query(args ...any) (*Rows, error)
- func (s *Stmt) QueryContext(ctx context.Context, args ...any) (*Rows, error)
- func (s *Stmt) QueryRow(args ...any) *Row
- func (s *Stmt) QueryRowContext(ctx context.Context, args ...any) *Row
-
type Tx
- func (tx *Tx) Commit() error
- func (tx *Tx) Exec(query string, args ...any) (Result, error)
- func (tx *Tx) ExecContext(ctx context.Context, query string, args ...any) (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 ...any) (*Rows, error)
- func (tx *Tx) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error)
- func (tx *Tx) QueryRow(query string, args ...any) *Row
- func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *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
Examples
- Conn.ExecContext
- DB.BeginTx
- DB.ExecContext
- DB.PingContext
- DB.Prepare
- DB.Query (MultipleResultSets)
- DB.QueryContext
- DB.QueryRowContext
- Rows
- Stmt
- Stmt.QueryRowContext
- Tx.ExecContext
- Tx.Prepare
- Tx.Rollback
- package (OpenDBCLI)
- package (OpenDBService)
Variables
var ErrConnDone = errors.New("sql: connection is already closed")
ErrConnDone 由任何在已归还到连接池的连接上执行的操作返回。
var ErrNoRows = errors.New("sql: no rows in result set")
ErrNoRows 由 Row.Scan 在 DB.QueryRow 未返回行时返回。 在这种情况下,QueryRow 返回一个占位的 *Row 值, 将该错误推迟到 Scan 时才产生。
var ErrTxDone = errors.New("sql: transaction has already been committed or rolled back")
ErrTxDone 由任何在已提交或已回滚的事务上执行的操作返回。
Functions
func Drivers
func Drivers() []string
Drivers 返回已注册驱动名称的排序列表。
func Register
func Register(name string, driver driver.Driver)
Register 使数据库驱动可以通过提供的名称使用。 如果以相同名称调用 Register 两次,或者 driver 为 nil, 它会 panic。
Types
type ColumnType
type ColumnType struct { // contains filtered or unexported fields }
ColumnType 包含列的名称和类型。
func (*ColumnType) DatabaseTypeName
func (ci *ColumnType) DatabaseTypeName() string
DatabaseTypeName 返回列类型的数据库系统名称。如果返回空字符串, 则表示不支持该驱动类型名称。 请查阅驱动文档以获取驱动数据类型的列表。ColumnType.Length 说明符不包含在内。 常见的类型名称包括 "VARCHAR"、"TEXT"、"NVARCHAR"、"DECIMAL"、"BOOL"、 "INT" 和 "BIGINT"。
func (*ColumnType) DecimalSize
func (ci *ColumnType) DecimalSize() (precision, scale int64, ok bool)
DecimalSize 返回 decimal 类型的标度和精度。 如果不适用,或如果驱动不支持,则 ok 为 false。
func (*ColumnType) Length
func (ci *ColumnType) Length() (length int64, ok bool)
Length 返回可变长度列类型(例如 text 和 binary 字段类型)的列类型长度。 如果类型长度无界,则值为 math.MaxInt64(任何数据库限制仍将适用)。 如果列类型不是可变长度的,例如 int,或如果驱动不支持,则 ok 为 false。
func (*ColumnType) Name
func (ci *ColumnType) Name() string
Name 返回列的名称或别名。
func (*ColumnType) Nullable
func (ci *ColumnType) Nullable() (nullable, ok bool)
Nullable 报告该列是否可为 null。 如果驱动不支持此属性,ok 将为 false。
func (*ColumnType) ScanType
func (ci *ColumnType) ScanType() reflect.Type
ScanType 返回一个适合用 Rows.Scan 扫描到的 Go 类型。 如果驱动不支持此属性,ScanType 将返回空接口的类型。
type Conn
type Conn struct { // contains filtered or unexported fields }
Conn 表示单个数据库连接,而不是数据库连接池。 除非确实需要持续的单个数据库连接,否则 优先使用 DB 运行查询。
Conn 必须调用 Conn.Close 将连接归还到数据库池, 并且可以在有查询运行的同时这样做。
调用 Conn.Close 之后,对该连接的所有操作 都会以 ErrConnDone 失败。
func (*Conn) BeginTx
func (c *Conn) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)
BeginTx 启动一个事务。
提供的 context 会一直使用到事务被提交或回滚。 如果 context 被取消,sql 包将回滚该事务。 如果提供给 BeginTx 的 context 被取消, Tx.Commit 将返回错误。
提供的 TxOptions 是可选的,如果应使用默认值则可以为 nil。 如果使用了驱动不支持的非默认隔离级别, 将返回错误。
func (*Conn) Close
func (c *Conn) Close() error
Close 将连接归还到连接池。 Close 之后的所有操作都将以 ErrConnDone 返回。 Close 可以与其他操作并发安全地调用,并且会 阻塞直到所有其他操作完成。先取消任何使用过的 context,然后紧接着调用 close 可能会有用。
func (*Conn) ExecContext
func (c *Conn) ExecContext(ctx context.Context, query string, args ...any) (Result, error)
ExecContext 执行一个不返回任何行的查询。
args 用于查询中的任何占位符参数。
Example
package main
import (
"context"
"database/sql"
"log"
)
var (
ctx context.Context
db *sql.DB
)
func main() {
// A *DB is a pool of connections. Call Conn to reserve a connection for
// exclusive use.
conn, err := db.Conn(ctx)
if err != nil {
log.Fatal(err)
}
defer conn.Close() // Return the connection to the pool.
id := 41
result, err := conn.ExecContext(ctx, `UPDATE balances SET balance = balance + 10 WHERE user_id = ?;`, id)
if err != nil {
log.Fatal(err)
}
rows, err := result.RowsAffected()
if err != nil {
log.Fatal(err)
}
if rows != 1 {
log.Fatalf("expected single row affected, got %d rows affected", rows)
}
}
func (*Conn) PingContext
func (c *Conn) PingContext(ctx context.Context) error
PingContext 验证到数据库的连接仍然有效。
func (*Conn) PrepareContext
func (c *Conn) PrepareContext(ctx context.Context, query string) (*Stmt, error)
PrepareContext 创建一个已准备的语句,供后续查询或执行使用。 多个查询或执行可以在返回的语句上并发运行。 当不再需要该语句时,调用方必须调用该语句的 *Stmt.Close 方法。
提供的 context 用于该语句的准备,而不是 该语句的执行。
func (*Conn) QueryContext
func (c *Conn) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error)
QueryContext 执行一个返回行的查询,通常是 SELECT。 args 用于查询中的任何占位符参数。
func (*Conn) QueryRowContext
func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...any) *Row
QueryRowContext 执行一个预期最多返回一行的查询。 QueryRowContext 始终返回非 nil 值。错误会被推迟到 调用 *Row.Scan 方法时才产生。 如果查询没有选中任何行,*Row.Scan 将返回 ErrNoRows。 否则,*Row.Scan 扫描第一个选中的行并丢弃 其余的行。
func (*Conn) Raw
func (c *Conn) Raw(f func(driverConn any) error) (err error)
Raw 在 f 的执行期间执行 f 并暴露底层驱动连接。 driverConn 不得在 f 之外使用。
一旦 f 返回且 err 不是 driver.ErrBadConn,Conn 将继续可用, 直到调用 Conn.Close。
type DB
type DB struct { // contains filtered or unexported fields }
DB 是一个数据库句柄,表示零个或多个底层连接的池。 它可以被多个 goroutine 并发安全地使用。
sql 包会自动创建和释放连接;它 还维护一个空闲连接池。如果数据库有 每连接状态的概念,这种状态可以在事务(Tx) 或连接(Conn)中被可靠地观察到。一旦调用 DB.Begin, 返回的 Tx 就绑定到一个单一连接。一旦对该事务 调用 Tx.Commit 或 Tx.Rollback,该事务的连接 就会被归还到 DB 的空闲连接池。池的大小 可以通过 DB.SetMaxIdleConns 控制。
func Open
func Open(driverName, dataSourceName string) (*DB, error)
Open 打开由其数据库驱动名称和驱动特定的数据源名称 指定的数据库,数据源名称通常至少包含 数据库名称和连接信息。
大多数用户会通过返回 *DB 的驱动特定连接辅助函数 来打开数据库。Go 标准库中不包含任何数据库驱动。 第三方驱动列表见 https://golang.org/s/sqldrivers。
Open 可能只验证其参数而不创建到数据库的连接。 要验证数据源名称是否有效,请调用 DB.Ping。
返回的 DB 可以被多个 goroutine 并发安全地使用, 并维护自己的空闲连接池。因此,Open 函数应当只被调用一次。很少需要 关闭 DB。
func OpenDB
func OpenDB(c driver.Connector) *DB
OpenDB 使用 driver.Connector 打开数据库,允许驱动 绕过基于字符串的数据源名称。
大多数用户会通过返回 *DB 的驱动特定连接辅助函数 来打开数据库。Go 标准库中不包含任何数据库驱动。 第三方驱动列表见 https://golang.org/s/sqldrivers。
OpenDB 可能只验证其参数而不创建到数据库的连接。 要验证数据源名称是否有效,请调用 DB.Ping。
返回的 DB 可以被多个 goroutine 并发安全地使用, 并维护自己的空闲连接池。因此,OpenDB 函数应当只被调用一次。很少需要 关闭 DB。
func (*DB) Begin
func (db *DB) Begin() (*Tx, error)
Begin 启动一个事务。默认隔离级别取决于 驱动。
Begin 内部使用 context.Background;要指定 context,请使用 DB.BeginTx。
func (*DB) BeginTx
func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)
BeginTx 启动一个事务。
提供的 context 会一直使用到事务被提交或回滚。 如果 context 被取消,sql 包将回滚该事务。 如果提供给 BeginTx 的 context 被取消, Tx.Commit 将返回错误。
提供的 TxOptions 是可选的,如果应使用默认值则可以为 nil。
如果使用了驱动不支持的非默认隔离级别,
将返回错误。
Example
package main
import (
"context"
"database/sql"
"log"
)
var (
ctx context.Context
db *sql.DB
)
func main() {
tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable})
if err != nil {
log.Fatal(err)
}
id := 37
_, execErr := tx.Exec(`UPDATE users SET status = ? WHERE id = ?`, "paid", id)
if execErr != nil {
_ = tx.Rollback()
log.Fatal(execErr)
}
if err := tx.Commit(); err != nil {
log.Fatal(err)
}
}
func (*DB) Close
func (db *DB) Close() error
Close 关闭数据库并阻止新查询开始。 然后 Close 会等待所有已在服务器上开始处理的查询 完成。
很少调用 Close 关闭 DB,因为 DB 句柄应当是 长期存在并在许多 goroutine 之间共享的。
func (*DB) Conn
func (db *DB) Conn(ctx context.Context) (*Conn, error)
Conn 通过打开新连接或从连接池返回现有连接来返回单个连接。 Conn 会阻塞,直到返回一个连接或 ctx 被取消。 在同一个 Conn 上运行的查询将在同一个数据库会话中运行。
每个 Conn 使用后都必须通过调用 Conn.Close 归还到数据库池。
func (*DB) Driver
func (db *DB) Driver() driver.Driver
Driver 返回数据库的底层驱动。
func (*DB) Exec
func (db *DB) Exec(query string, args ...any) (Result, error)
Exec 执行一个不返回任何行的查询。 args 用于查询中的任何占位符参数。
Exec 内部使用 context.Background;要指定 context,请使用 DB.ExecContext。
func (*DB) ExecContext
func (db *DB) ExecContext(ctx context.Context, query string, args ...any) (Result, error)
ExecContext 执行一个不返回任何行的查询。
args 用于查询中的任何占位符参数。
Example
package main
import (
"context"
"database/sql"
"log"
)
var (
ctx context.Context
db *sql.DB
)
func main() {
id := 47
result, err := db.ExecContext(ctx, "UPDATE balances SET balance = balance + 10 WHERE user_id = ?", id)
if err != nil {
log.Fatal(err)
}
rows, err := result.RowsAffected()
if err != nil {
log.Fatal(err)
}
if rows != 1 {
log.Fatalf("expected to affect 1 row, affected %d", rows)
}
}
func (*DB) Ping
func (db *DB) Ping() error
Ping 验证到数据库的连接仍然有效, 必要时会建立连接。
Ping 内部使用 context.Background;要指定 context,请使用 DB.PingContext。
func (*DB) PingContext
func (db *DB) PingContext(ctx context.Context) error
PingContext 验证到数据库的连接仍然有效,
必要时会建立连接。
Example
package main
import (
"context"
"database/sql"
"log"
"time"
)
var (
ctx context.Context
db *sql.DB
)
func main() {
// Ping and PingContext may be used to determine if communication with
// the database server is still possible.
//
// When used in a command line application Ping may be used to establish
// that further queries are possible; that the provided DSN is valid.
//
// When used in long running service Ping may be part of the health
// checking system.
ctx, cancel := context.WithTimeout(ctx, 1*time.Second)
defer cancel()
status := "up"
if err := db.PingContext(ctx); err != nil {
status = "down"
}
log.Println(status)
}
func (*DB) Prepare
func (db *DB) Prepare(query string) (*Stmt, error)
Prepare 创建一个已准备的语句,供后续查询或执行使用。 多个查询或执行可以在返回的语句上并发运行。 当不再需要该语句时,调用方必须调用该语句的 *Stmt.Close 方法。
Prepare 内部使用 context.Background;要指定 context,请使用
DB.PrepareContext。
Example
package main
import (
"context"
"database/sql"
"log"
)
var db *sql.DB
func main() {
projects := []struct {
mascot string
release int
}{
{"tux", 1991},
{"duke", 1996},
{"gopher", 2009},
{"moby dock", 2013},
}
stmt, err := db.Prepare("INSERT INTO projects(id, mascot, release, category) VALUES( ?, ?, ?, ? )")
if err != nil {
log.Fatal(err)
}
defer stmt.Close() // Prepared statements take up server resources and should be closed after use.
for id, project := range projects {
if _, err := stmt.Exec(id+1, project.mascot, project.release, "open source"); err != nil {
log.Fatal(err)
}
}
}
func (*DB) PrepareContext
func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error)
PrepareContext 创建一个已准备的语句,供后续查询或执行使用。 多个查询或执行可以在返回的语句上并发运行。 当不再需要该语句时,调用方必须调用该语句的 *Stmt.Close 方法。
提供的 context 用于该语句的准备,而不是 该语句的执行。
func (*DB) Query
func (db *DB) Query(query string, args ...any) (*Rows, error)
Query 执行一个返回行的查询,通常是 SELECT。 args 用于查询中的任何占位符参数。
Query 内部使用 context.Background;要指定 context,请使用
DB.QueryContext。
Example (MultipleResultSets)
package main
import (
"context"
"database/sql"
"log"
)
var db *sql.DB
func main() {
age := 27
q := `
create temp table uid (id bigint); -- Create temp table for queries.
insert into uid
select id from users where age < ?; -- Populate temp table.
-- First result set.
select
users.id, name
from
users
join uid on users.id = uid.id
;
-- Second result set.
select
ur.user, ur.role
from
user_roles as ur
join uid on uid.id = ur.user
;
`
rows, err := db.Query(q, age)
if err != nil {
log.Fatal(err)
}
defer rows.Close()
for rows.Next() {
var (
id int64
name string
)
if err := rows.Scan(&id, &name); err != nil {
log.Fatal(err)
}
log.Printf("id %d name is %s\n", id, name)
}
if !rows.NextResultSet() {
log.Fatalf("expected more result sets: %v", rows.Err())
}
var roleMap = map[int64]string{
1: "user",
2: "admin",
3: "gopher",
}
for rows.Next() {
var (
id int64
role int64
)
if err := rows.Scan(&id, &role); err != nil {
log.Fatal(err)
}
log.Printf("id %d has role %s\n", id, roleMap[role])
}
if err := rows.Err(); err != nil {
log.Fatal(err)
}
}
func (*DB) QueryContext
func (db *DB) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error)
QueryContext 执行一个返回行的查询,通常是 SELECT。
args 用于查询中的任何占位符参数。
Example
package main
import (
"context"
"database/sql"
"fmt"
"log"
"strings"
)
var (
ctx context.Context
db *sql.DB
)
func main() {
age := 27
rows, err := db.QueryContext(ctx, "SELECT name FROM users WHERE age=?", age)
if err != nil {
log.Fatal(err)
}
defer rows.Close()
names := make([]string, 0)
for rows.Next() {
var name string
if err := rows.Scan(&name); err != nil {
// Check for a scan error.
// Query rows will be closed with defer.
log.Fatal(err)
}
names = append(names, name)
}
// If the database is being written to ensure to check for Close
// errors that may be returned from the driver. The query may
// encounter an auto-commit error and be forced to rollback changes.
rerr := rows.Close()
if rerr != nil {
log.Fatal(rerr)
}
// Rows.Err will report the last error encountered by Rows.Scan.
if err := rows.Err(); err != nil {
log.Fatal(err)
}
fmt.Printf("%s are %d years old", strings.Join(names, ", "), age)
}
func (*DB) QueryRow
func (db *DB) QueryRow(query string, args ...any) *Row
QueryRow 执行一个预期最多返回一行的查询。 QueryRow 始终返回非 nil 值。错误会被推迟到 调用 Row 的 Scan 方法时才产生。 如果查询没有选中任何行,*Row.Scan 将返回 ErrNoRows。 否则,*Row.Scan 扫描第一个选中的行并丢弃 其余的行。
QueryRow 内部使用 context.Background;要指定 context,请使用 DB.QueryRowContext。
func (*DB) QueryRowContext
func (db *DB) QueryRowContext(ctx context.Context, query string, args ...any) *Row
QueryRowContext 执行一个预期最多返回一行的查询。
QueryRowContext 始终返回非 nil 值。错误会被推迟到
调用 Row 的 Scan 方法时才产生。
如果查询没有选中任何行,*Row.Scan 将返回 ErrNoRows。
否则,*Row.Scan 扫描第一个选中的行并丢弃
其余的行。
Example
package main
import (
"context"
"database/sql"
"log"
"time"
)
var (
ctx context.Context
db *sql.DB
)
func main() {
id := 123
var username string
var created time.Time
err := db.QueryRowContext(ctx, "SELECT username, created_at FROM users WHERE id=?", id).Scan(&username, &created)
switch {
case err == sql.ErrNoRows:
log.Printf("no user with id %d\n", id)
case err != nil:
log.Fatalf("query error: %v\n", err)
default:
log.Printf("username is %q, account created on %s\n", username, created)
}
}
func (*DB) SetConnMaxIdleTime
func (db *DB) SetConnMaxIdleTime(d time.Duration)
SetConnMaxIdleTime 设置连接可处于空闲状态的最长时间。
已过期的连接可能会在复用前被延迟关闭。
如果 d <= 0,则连接不会因空闲时间过长而被关闭。
func (*DB) SetConnMaxLifetime
func (db *DB) SetConnMaxLifetime(d time.Duration)
SetConnMaxLifetime 设置连接可被复用的最长时间。
已过期的连接可能会在复用前被延迟关闭。
如果 d <= 0,则连接不会因存在时间过长而被关闭。
func (*DB) SetMaxIdleConns
func (db *DB) SetMaxIdleConns(n int)
SetMaxIdleConns 设置空闲连接池中连接的最大数量。
如果 MaxOpenConns 大于 0 但小于新的 MaxIdleConns, 那么新的 MaxIdleConns 会被缩减以匹配 MaxOpenConns 限制。
如果 n <= 0,则不保留任何空闲连接。
默认的最大空闲连接数目前为 2。这可能在 未来版本中改变。
func (*DB) SetMaxOpenConns
func (db *DB) SetMaxOpenConns(n int)
SetMaxOpenConns 设置到数据库的打开连接的最大数量。
如果 MaxIdleConns 大于 0 且新的 MaxOpenConns 小于 MaxIdleConns,那么 MaxIdleConns 会被缩减以匹配新的 MaxOpenConns 限制。
如果 n <= 0,则对打开连接的数量没有限制。 默认值为 0(无限制)。
func (*DB) Stats
func (db *DB) Stats() DBStats
Stats 返回数据库统计信息。
type DBStats
type DBStats struct { MaxOpenConnections int // 到数据库的打开连接的最大数量。 // 池状态 OpenConnections int // 已建立连接的数量,包括使用中和空闲的。 InUse int // 当前正在使用的连接数量。 Idle int // 空闲连接的数量。 // 计数器 WaitCount int64 // 等待过的连接总数。 WaitDuration time.Duration // 等待新连接而被阻塞的总时间。 MaxIdleClosed int64 // 因 SetMaxIdleConns 而被关闭的连接总数。 MaxIdleTimeClosed int64 // 因 SetConnMaxIdleTime 而被关闭的连接总数。 MaxLifetimeClosed int64 // 因 SetConnMaxLifetime 而被关闭的连接总数。 }
DBStats 包含数据库统计信息。
type IsolationLevel
type IsolationLevel int
IsolationLevel 是 TxOptions 中使用的事务隔离级别。
const ( LevelDefault IsolationLevel = iota LevelReadUncommitted LevelReadCommitted LevelWriteCommitted LevelRepeatableRead LevelSnapshot LevelSerializable LevelLinearizable )
驱动可以在 DB.BeginTx 中支持的各种隔离级别。 如果驱动不支持给定的隔离级别,可能会返回错误。
参见 https://en.wikipedia.org/wiki/Isolation_(database_systems)#Isolation_levels。
func (IsolationLevel) String
func (i IsolationLevel) String() string
String 返回事务隔离级别的名称。
type NamedArg
type NamedArg struct { // Name 是参数占位符的名称。 // // 如果为空,将使用参数列表中的 // 序号位置。 // // Name 必须省略任何符号前缀。 Name string // Value 是参数的值。 // 它可以被赋予与查询参数 // 相同的值类型。 Value any // contains filtered or unexported fields }
NamedArg 是一个命名参数。NamedArg 值可用作 DB.Query 或 DB.Exec 的参数,并绑定到 SQL 语句中 对应的命名参数。
有关创建 NamedArg 值的更简洁方式,见 Named 函数。
func Named
func Named(name string, value any) NamedArg
Named 提供了创建 NamedArg 值的更简洁方式。
用法示例:
db.ExecContext(ctx, `
delete from Invoice
where
TimeCreated < @end
and TimeCreated >= @start;`,
sql.Named("start", startTime),
sql.Named("end", endTime),
)
type Null
type Null[T any] struct { V T Valid bool }
Null 表示一个可能为 null 的值。 Null 实现了 Scanner 接口,因此 它可以用作扫描目标:
var s Null[string]
err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s)
...
if s.Valid {
// 使用 s.V
} else {
// NULL 值
}
T 应为 driver.Value 所接受的类型之一。
func (*Null[T]) Scan
func (n *Null[T]) Scan(value any) error
func (Null[T]) Value
func (n Null[T]) Value() (driver.Value, error)
type NullBool
type NullBool struct { Bool bool Valid bool // 如果 Bool 不为 NULL,则 Valid 为 true }
NullBool 表示一个可能为 null 的 bool。 NullBool 实现了 Scanner 接口,因此 它可以用作扫描目标,类似于 NullString。
func (*NullBool) Scan
func (n *NullBool) Scan(value any) error
Scan 实现了 Scanner 接口。
func (NullBool) Value
func (n NullBool) Value() (driver.Value, error)
Value 实现了 driver.Valuer 接口。
type NullByte
type NullByte struct { Byte byte Valid bool // 如果 Byte 不为 NULL,则 Valid 为 true }
NullByte 表示一个可能为 null 的 byte。 NullByte 实现了 Scanner 接口,因此 它可以用作扫描目标,类似于 NullString。
func (*NullByte) Scan
func (n *NullByte) Scan(value any) error
Scan 实现了 Scanner 接口。
func (NullByte) Value
func (n NullByte) Value() (driver.Value, error)
Value 实现了 driver.Valuer 接口。
type NullFloat64
type NullFloat64 struct { Float64 float64 Valid bool // 如果 Float64 不为 NULL,则 Valid 为 true }
NullFloat64 表示一个可能为 null 的 float64。 NullFloat64 实现了 Scanner 接口,因此 它可以用作扫描目标,类似于 NullString。
func (*NullFloat64) Scan
func (n *NullFloat64) Scan(value any) error
Scan 实现了 Scanner 接口。
func (NullFloat64) Value
func (n NullFloat64) Value() (driver.Value, error)
Value 实现了 driver.Valuer 接口。
type NullInt16
type NullInt16 struct { Int16 int16 Valid bool // 如果 Int16 不为 NULL,则 Valid 为 true }
NullInt16 表示一个可能为 null 的 int16。 NullInt16 实现了 Scanner 接口,因此 它可以用作扫描目标,类似于 NullString。
func (*NullInt16) Scan
func (n *NullInt16) Scan(value any) error
Scan 实现了 Scanner 接口。
func (NullInt16) Value
func (n NullInt16) Value() (driver.Value, error)
Value 实现了 driver.Valuer 接口。
type NullInt32
type NullInt32 struct { Int32 int32 Valid bool // 如果 Int32 不为 NULL,则 Valid 为 true }
NullInt32 表示一个可能为 null 的 int32。 NullInt32 实现了 Scanner 接口,因此 它可以用作扫描目标,类似于 NullString。
func (*NullInt32) Scan
func (n *NullInt32) Scan(value any) error
Scan 实现了 Scanner 接口。
func (NullInt32) Value
func (n NullInt32) Value() (driver.Value, error)
Value 实现了 driver.Valuer 接口。
type NullInt64
type NullInt64 struct { Int64 int64 Valid bool // 如果 Int64 不为 NULL,则 Valid 为 true }
NullInt64 表示一个可能为 null 的 int64。 NullInt64 实现了 Scanner 接口,因此 它可以用作扫描目标,类似于 NullString。
func (*NullInt64) Scan
func (n *NullInt64) Scan(value any) error
Scan 实现了 Scanner 接口。
func (NullInt64) Value
func (n NullInt64) Value() (driver.Value, error)
Value 实现了 driver.Valuer 接口。
type NullString
type NullString struct { String string Valid bool // 如果 String 不为 NULL,则 Valid 为 true }
NullString 表示一个可能为 null 的字符串。 NullString 实现了 Scanner 接口,因此 它可以用作扫描目标:
var s NullString
err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s)
...
if s.Valid {
// 使用 s.String
} else {
// NULL 值
}
func (*NullString) Scan
func (ns *NullString) Scan(value any) error
Scan 实现了 Scanner 接口。
func (NullString) Value
func (ns NullString) Value() (driver.Value, error)
Value 实现了 driver.Valuer 接口。
type NullTime
type NullTime struct { Time time.Time Valid bool // 如果 Time 不为 NULL,则 Valid 为 true }
NullTime 表示一个可能为 null 的 time.Time。 NullTime 实现了 Scanner 接口,因此 它可以用作扫描目标,类似于 NullString。
func (*NullTime) Scan
func (n *NullTime) Scan(value any) error
Scan 实现了 Scanner 接口。
func (NullTime) Value
func (n NullTime) Value() (driver.Value, error)
Value 实现了 driver.Valuer 接口。
type Out
type Out struct { // Dest 是一个指针,指向将被设置为存储过程 // OUTPUT 参数结果的值。 Dest any // In 表示参数是否为 INOUT 参数。如果是,存储过程的 // 输入值是 Dest 指针解引用后的值,随后该值会被 // 输出值替换。 In bool // contains filtered or unexported fields }
Out 可用于从存储过程检索 OUTPUT 值参数。
并非所有驱动和数据库都支持 OUTPUT 值参数。
用法示例:
var outArg string
_, err := db.ExecContext(ctx, "ProcName", sql.Named("Arg1", sql.Out{Dest: &outArg}))
type RawBytes
type RawBytes []byte
RawBytes 是一个字节切片,持有对数据库自身拥有的内存的引用。 将 Rows.Scan 扫描到 RawBytes 之后,该切片仅在 下次调用 Rows.Next、Rows.Scan 或 Rows.Close 之前有效。
type Result
type Result interface { // LastInsertId 返回数据库为响应命令而生成的整数。 // 通常这来自插入新行时的 "auto increment" 列。 // 并非所有数据库都支持此特性,且此类语句的语法各不相同。 LastInsertId() (int64, error) // RowsAffected 返回受 update、insert 或 delete 影响的行数。 // 并非每个数据库或数据库驱动都支持此功能。 RowsAffected() (int64, error) }
Result 汇总了一条已执行的 SQL 命令。
type Row
type Row struct { // contains filtered or unexported fields }
Row 是调用 DB.QueryRow 以选择单行的结果。
func (*Row) Err
func (r *Row) Err() error
Err 为包装包提供了一种在不调用 Row.Scan 的情况下检查 查询错误的方式。 Err 返回在运行查询时遇到的错误(如果有)。 如果此错误不为 nil,则 Row.Scan 也会返回此错误。
func (*Row) Scan
func (r *Row) Scan(dest ...any) error
Scan 将匹配行中的列复制到 dest 所指向的值。 详情请参阅 Rows.Scan 的文档。 如果有多行匹配该查询,Scan 使用第一行并丢弃其余的。 如果没有行匹配该查询,Scan 返回 ErrNoRows。
type Rows
type Rows struct { // contains filtered or unexported fields }
Rows 是一次查询的结果。它的游标从结果集的第一行之前
开始。使用 Rows.Next 逐行前进。
Example
package main
import (
"context"
"database/sql"
"log"
"strings"
)
var (
ctx context.Context
db *sql.DB
)
func main() {
age := 27
rows, err := db.QueryContext(ctx, "SELECT name FROM users WHERE age=?", age)
if err != nil {
log.Fatal(err)
}
defer rows.Close()
names := make([]string, 0)
for rows.Next() {
var name string
if err := rows.Scan(&name); err != nil {
log.Fatal(err)
}
names = append(names, name)
}
// Check for errors from iterating over rows.
if err := rows.Err(); err != nil {
log.Fatal(err)
}
log.Printf("%s are %d years old", strings.Join(names, ", "), age)
}
func (*Rows) Close
func (rs *Rows) Close() error
Close 关闭 Rows,阻止进一步枚举。如果调用 Rows.Next 并返回 false 且没有更多结果集,Rows 会自动关闭, 此时只需检查 Rows.Err 的结果即可。Close 是幂等的, 且不影响 Rows.Err 的结果。
func (*Rows) ColumnTypes
func (rs *Rows) ColumnTypes() ([]*ColumnType, error)
ColumnTypes 返回列信息,例如列类型、长度和是否可为 null。 某些信息可能无法从某些驱动获取。
func (*Rows) Columns
func (rs *Rows) Columns() ([]string, error)
Columns 返回列名。 如果 rows 已关闭,Columns 返回一个错误。
func (*Rows) Err
func (rs *Rows) Err() error
Err 返回在迭代过程中遇到的错误(如果有)。 可以在显式或隐式调用 Rows.Close 之后调用 Err。
func (*Rows) Next
func (rs *Rows) Next() bool
Next 准备下一行结果,以便用 Rows.Scan 方法读取。如果成功则返回 true; 如果没有下一行结果,或在准备过程中发生错误,则返回 false。Rows.Err 应被用于区分这两种情况。
每一次对 Rows.Scan 的调用,即使是第一次,都必须先调用 Rows.Next。
func (*Rows) NextResultSet
func (rs *Rows) NextResultSet() bool
NextResultSet 准备下一个结果集以供读取。它报告是否还有更多结果集; 如果没有更多结果集,或在推进到下一个结果集时发生错误,则返回 false。 Rows.Err 方法应被用于区分这两种情况。
在调用 NextResultSet 之后,在扫描之前应始终先调用 Rows.Next 方法。 如果还有更多结果集,它们可能在结果集中没有行。
func (*Rows) Scan
func (rs *Rows) Scan(dest ...any) error
Scan 将当前行中的列复制到 dest 所指向的值。dest 中的值的数量 必须与 Rows 中的列数相同。
Scan 将从数据库读取的列转换为以下 常见 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)
在最简单的情况下,如果源列值的类型为整数、bool 或字符串类型 T, 而 dest 的类型为 *T,Scan 只需通过指针赋值。
只要不丢失信息,Scan 也可以在字符串和数值类型之间转换。虽然 Scan 会将 从数值数据库列扫描到的所有数字字符串化写入 *string,但扫描到 数值类型时会检查溢出。例如,值为 300 的 float64 或值为 "300" 的字符串 可以扫描进 uint16,但不能扫描进 uint8,尽管 float64(255) 或 "255" 可以扫描进 uint8。一个例外是,某些 float64 数字扫描到字符串时 在字符串化过程中可能丢失信息。一般而言,应将浮点列扫描进 *float64。
如果某个 dest 参数的类型为 *[]byte,Scan 会在该参数中保存 相应数据的副本。该副本归调用者所有, 可以被修改并无限期持有。可以通过改用类型为 *RawBytes 的参数 来避免复制;关于其使用的限制,请参阅 RawBytes 的文档。
如果某个参数的类型为 *interface{},Scan 会不经转换地复制 底层驱动提供的值。当从类型为 []byte 的源值扫描到 *interface{} 时, 会制作该切片的一个副本,结果归调用者所有。
类型为 time.Time 的源值可以被扫描进类型为 *time.Time、*interface{}、*string 或 *[]byte 的值。当转换为 后两者时,使用 time.RFC3339Nano。
类型为 bool 的源值可以被扫描进类型 *bool、 *interface{}、*string、*[]byte 或 *RawBytes。
对于扫描进 *bool,源可以是 true、false、1、0,或 可被 strconv.ParseBool 解析的字符串输入。
Scan 还可以将查询返回的游标(例如 "select cursor(select * from my_table) from dual")转换为 一个 *Rows 值,该值本身可以被扫描。如果父 *Rows 被关闭, 父 select 查询将关闭任何游标 *Rows。
如果任何实现 Scanner 的前导参数返回错误, 该错误将被包装在返回的错误中。
type Scanner
type Scanner interface { // Scan 从数据库驱动赋值一个值。 // // src 值将是以下类型之一: // // int64 // float64 // bool // []byte // string // time.Time // nil - 表示 NULL 值 // // 如果值无法在不丢失信息的情况下被存储, // 则应返回错误。 // // []byte 之类的引用类型仅在下次调用 Scan 之前有效, // 不应被保留。它们的底层内存归驱动所有。 // 如果必须保留,请在下次调用 Scan 之前复制其值。 Scan(src any) error }
Scanner 是 Rows.Scan 使用的接口。
type Stmt
type Stmt struct { // contains filtered or unexported fields }
Stmt 是一个已准备的语句。 Stmt 可以被多个 goroutine 并发安全地使用。
如果 Stmt 是在 Tx 或 Conn 上准备的,它将永远绑定到单个
底层连接。如果 Tx 或 Conn 关闭,Stmt 将
变得不可用,所有操作都会返回错误。
如果 Stmt 是在 DB 上准备的,它在 DB 的生命周期内
保持可用。当 Stmt 需要在一个新的底层连接上执行时,
它会自动在新连接上准备自身。
Example
package main
import (
"context"
"database/sql"
"log"
)
var (
ctx context.Context
db *sql.DB
)
func main() {
// In normal use, create one Stmt when your process starts.
stmt, err := db.PrepareContext(ctx, "SELECT username FROM users WHERE id = ?")
if err != nil {
log.Fatal(err)
}
defer stmt.Close()
// Then reuse it each time you need to issue the query.
id := 43
var username string
err = stmt.QueryRowContext(ctx, id).Scan(&username)
switch {
case err == sql.ErrNoRows:
log.Fatalf("no user with id %d", id)
case err != nil:
log.Fatal(err)
default:
log.Printf("username is %s\n", username)
}
}
func (*Stmt) Close
func (s *Stmt) Close() error
Close 关闭该语句。
func (*Stmt) Exec
func (s *Stmt) Exec(args ...any) (Result, error)
Exec 使用给定参数执行一个已准备的语句, 并返回一个概述该语句效果的 Result。
Exec 内部使用 context.Background;要指定 context,请使用 Stmt.ExecContext。
func (*Stmt) ExecContext
func (s *Stmt) ExecContext(ctx context.Context, args ...any) (Result, error)
ExecContext 使用给定参数执行一个已准备的语句, 并返回一个概述该语句效果的 Result。
func (*Stmt) Query
func (s *Stmt) Query(args ...any) (*Rows, error)
Query 使用给定参数执行一个已准备的查询语句, 并将查询结果作为 *Rows 返回。
Query 内部使用 context.Background;要指定 context,请使用 Stmt.QueryContext。
func (*Stmt) QueryContext
func (s *Stmt) QueryContext(ctx context.Context, args ...any) (*Rows, error)
QueryContext 使用给定参数执行一个已准备的查询语句, 并将查询结果作为 *Rows 返回。
func (*Stmt) QueryRow
func (s *Stmt) QueryRow(args ...any) *Row
QueryRow 使用给定参数执行一个已准备的查询语句。 如果语句执行期间发生错误,该错误将由对返回的 *Row 调用 Scan 时返回,而 *Row 始终非 nil。 如果查询没有选中任何行,*Row.Scan 将返回 ErrNoRows。 否则,*Row.Scan 扫描第一个选中的行并丢弃 其余的行。
用法示例:
var name string err := nameByUseridStmt.QueryRow(id).Scan(&name)
QueryRow 内部使用 context.Background;要指定 context,请使用 Stmt.QueryRowContext。
func (*Stmt) QueryRowContext
func (s *Stmt) QueryRowContext(ctx context.Context, args ...any) *Row
QueryRowContext 使用给定参数执行一个已准备的查询语句。
如果语句执行期间发生错误,该错误将由对返回的 *Row
调用 Scan 时返回,而 *Row 始终非 nil。
如果查询没有选中任何行,*Row.Scan 将返回 ErrNoRows。
否则,*Row.Scan 扫描第一个选中的行并丢弃
其余的行。
Example
package main
import (
"context"
"database/sql"
"log"
)
var (
ctx context.Context
db *sql.DB
)
func main() {
// In normal use, create one Stmt when your process starts.
stmt, err := db.PrepareContext(ctx, "SELECT username FROM users WHERE id = ?")
if err != nil {
log.Fatal(err)
}
defer stmt.Close()
// Then reuse it each time you need to issue the query.
id := 43
var username string
err = stmt.QueryRowContext(ctx, id).Scan(&username)
switch {
case err == sql.ErrNoRows:
log.Fatalf("no user with id %d", id)
case err != nil:
log.Fatal(err)
default:
log.Printf("username is %s\n", username)
}
}
type Tx
type Tx struct { // contains filtered or unexported fields }
Tx 是一个进行中的数据库事务。
事务必须以调用 Tx.Commit 或 Tx.Rollback 结束。
调用 Tx.Commit 或 Tx.Rollback 之后,对该事务的所有操作 都会以 ErrTxDone 失败。
通过调用事务的 Tx.Prepare 或 Tx.Stmt 方法为该事务 准备的语句,会在调用 Tx.Commit 或 Tx.Rollback 时 被关闭。
func (*Tx) Commit
func (tx *Tx) Commit() error
Commit 提交事务。
func (*Tx) Exec
func (tx *Tx) Exec(query string, args ...any) (Result, error)
Exec 执行一个不返回行的查询。 例如:INSERT 和 UPDATE。
Exec 内部使用 context.Background;要指定 context,请使用 Tx.ExecContext。
func (*Tx) ExecContext
func (tx *Tx) ExecContext(ctx context.Context, query string, args ...any) (Result, error)
ExecContext 执行一个不返回行的查询。
例如:INSERT 和 UPDATE。
Example
package main
import (
"context"
"database/sql"
"log"
)
var (
ctx context.Context
db *sql.DB
)
func main() {
tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable})
if err != nil {
log.Fatal(err)
}
id := 37
_, execErr := tx.ExecContext(ctx, "UPDATE users SET status = ? WHERE id = ?", "paid", id)
if execErr != nil {
if rollbackErr := tx.Rollback(); rollbackErr != nil {
log.Fatalf("update failed: %v, unable to rollback: %v\n", execErr, rollbackErr)
}
log.Fatalf("update failed: %v", execErr)
}
if err := tx.Commit(); err != nil {
log.Fatal(err)
}
}
func (*Tx) Prepare
func (tx *Tx) Prepare(query string) (*Stmt, error)
Prepare 创建一个在事务内使用的已准备语句。
返回的语句在事务内运行,并会在事务被提交或 回滚时被关闭。
要在该事务上使用已有的已准备语句,见 Tx.Stmt。
Prepare 内部使用 context.Background;要指定 context,请使用
Tx.PrepareContext。
Example
package main
import (
"context"
"database/sql"
"log"
)
var db *sql.DB
func main() {
projects := []struct {
mascot string
release int
}{
{"tux", 1991},
{"duke", 1996},
{"gopher", 2009},
{"moby dock", 2013},
}
tx, err := db.Begin()
if err != nil {
log.Fatal(err)
}
defer tx.Rollback() // The rollback will be ignored if the tx has been committed later in the function.
stmt, err := tx.Prepare("INSERT INTO projects(id, mascot, release, category) VALUES( ?, ?, ?, ? )")
if err != nil {
log.Fatal(err)
}
defer stmt.Close() // Prepared statements take up server resources and should be closed after use.
for id, project := range projects {
if _, err := stmt.Exec(id+1, project.mascot, project.release, "open source"); err != nil {
log.Fatal(err)
}
}
if err := tx.Commit(); err != nil {
log.Fatal(err)
}
}
func (*Tx) PrepareContext
func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error)
PrepareContext 创建一个在事务内使用的已准备语句。
返回的语句在事务内运行,并会在事务被提交或 回滚时被关闭。
要在该事务上使用已有的已准备语句,见 Tx.Stmt。
提供的 context 将用于该 context 的准备,而不是 返回语句的执行。返回的语句 将在事务 context 中运行。
func (*Tx) Query
func (tx *Tx) Query(query string, args ...any) (*Rows, error)
Query 执行一个返回行的查询,通常是 SELECT。
Query 内部使用 context.Background;要指定 context,请使用 Tx.QueryContext。
func (*Tx) QueryContext
func (tx *Tx) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error)
QueryContext 执行一个返回行的查询,通常是 SELECT。
func (*Tx) QueryRow
func (tx *Tx) QueryRow(query string, args ...any) *Row
QueryRow 执行一个预期最多返回一行的查询。 QueryRow 始终返回非 nil 值。错误会被推迟到 调用 Row 的 Scan 方法时才产生。 如果查询没有选中任何行,*Row.Scan 将返回 ErrNoRows。 否则,*Row.Scan 扫描第一个选中的行并丢弃 其余的行。
QueryRow 内部使用 context.Background;要指定 context,请使用 Tx.QueryRowContext。
func (*Tx) QueryRowContext
func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *Row
QueryRowContext 执行一个预期最多返回一行的查询。 QueryRowContext 始终返回非 nil 值。错误会被推迟到 调用 Row 的 Scan 方法时才产生。 如果查询没有选中任何行,*Row.Scan 将返回 ErrNoRows。 否则,*Row.Scan 扫描第一个选中的行并丢弃 其余的行。
func (*Tx) Rollback
func (tx *Tx) Rollback() error
Rollback 中止事务。
Example
package main
import (
"context"
"database/sql"
"log"
)
var (
ctx context.Context
db *sql.DB
)
func main() {
tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable})
if err != nil {
log.Fatal(err)
}
id := 53
_, err = tx.ExecContext(ctx, "UPDATE drivers SET status = ? WHERE id = ?;", "assigned", id)
if err != nil {
if rollbackErr := tx.Rollback(); rollbackErr != nil {
log.Fatalf("update drivers: unable to rollback: %v", rollbackErr)
}
log.Fatal(err)
}
_, err = tx.ExecContext(ctx, "UPDATE pickups SET driver_id = $1;", id)
if err != nil {
if rollbackErr := tx.Rollback(); rollbackErr != nil {
log.Fatalf("update failed: %v, unable to back: %v", err, rollbackErr)
}
log.Fatal(err)
}
if err := tx.Commit(); err != nil {
log.Fatal(err)
}
}
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)
返回的语句在事务内运行,并会在事务被提交或 回滚时被关闭。
Stmt 内部使用 context.Background;要指定 context,请使用 Tx.StmtContext。
func (*Tx) StmtContext
func (tx *Tx) StmtContext(ctx context.Context, stmt *Stmt) *Stmt
StmtContext 从已有的语句返回一个特定于事务的已准备语句。
示例:
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)
提供的 context 用于该语句的准备,而不是 该语句的执行。
返回的语句在事务内运行,并会在事务被提交或 回滚时被关闭。
type TxOptions
type TxOptions struct { // Isolation 是事务隔离级别。 // 如果为零,则使用驱动或数据库的默认级别。 Isolation IsolationLevel ReadOnly bool }
TxOptions 保存 DB.BeginTx 中使用的事务选项。
Directories
| driver | Package driver 定义了由数据库驱动实现的接口, 供 package sql 使用。 |