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

Examples

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 使用。