sql.Stmt 复用预编译语句并绑定连接的实践示例

在 Go 的 database/sql 中，重复执行同一条 SQL 时可以把语句先准备成 *sql.Stmt，之后只传入参数。真正容易混淆的是：从 *sql.DB 准备的语句可以跟随连接池复用，而从 *sql.Conn 准备的语句会绑定到这一条保留连接。两种写法都能复用 SQL，但生命周期和适用场景不同。

普通业务优先使用 DB.PrepareContext，让 sql.DB 管理底层连接；只有需要会话级状态或必须固定连接时，才使用 DB.Conn 后再调用 Conn.PrepareContext。无论哪种方式，语句不再使用时都应关闭。

官方资料：https://pkg.go.dev/database/sql

先看清两种准备方式的边界

*sql.DB 是可长期共享的连接池句柄，不等于某一条固定数据库连接。调用 db.PrepareContext 得到的 Stmt 可以被多个 goroutine 并发使用；执行时由 database/sql 选择可用连接，并在需要时为该连接准备语句。

db.Conn(ctx) 则会保留一条底层连接。基于这条连接调用 conn.PrepareContext 后，得到的 Stmt 永久绑定该连接。连接一旦关闭，绑定的语句也不能继续使用。这正是“复用预编译语句”和“绑定连接”之间的核心差别。

在连接池上复用 sql.Stmt

当一条 SQL 会被反复执行，但不要求每次使用同一条底层连接时，准备语句可以放在服务初始化阶段或一个可复用的仓储对象中。每次调用只传参数，避免把用户输入拼接进 SQL 文本。

package repository

import (
	"context"
	"database/sql"
)

type UserWriter struct {
	// Stmt 保存重复使用的 SQL，底层连接仍由 DB 连接池管理。
	stmt *sql.Stmt
}

func NewUserWriter(ctx context.Context, db *sql.DB) (*UserWriter, error) {
	stmt, err := db.PrepareContext(ctx,
		`INSERT INTO users(name, email) VALUES (?, ?)`)
	if err != nil {
		return nil, err
	}
	return &UserWriter{stmt: stmt}, nil
}

func (w *UserWriter) Add(ctx context.Context, name, email string) error {
	// 参数单独传入，避免用字符串格式化拼接 SQL。
	_, err := w.stmt.ExecContext(ctx, name, email)
	return err
}

func (w *UserWriter) Close() error {
	// 组件停止时关闭语句，释放预编译语句相关资源。
	return w.stmt.Close()
}

这里的 ? 只是示例占位符，实际语法由数据库驱动决定，例如某些 PostgreSQL 驱动使用 $1、$2。Stmt 可以并发使用，但关闭动作应由拥有它的组件统一负责，不要让每个请求都重复调用 Prepare 和 Close。

需要固定连接时再使用 Conn.PrepareContext

有些操作需要在同一条连接上连续完成，例如依赖连接级临时状态、特定会话设置或驱动提供的连接级能力。这时先向连接池申请一条 *sql.Conn，再在这条连接上准备语句。申请成功后，conn.Close 是必须安排的归还动作。

func insertOnOneConn(ctx context.Context, db *sql.DB, name string) error {
	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	// Conn.Close 归还保留的底层连接，而不是关闭整个 DB。
	defer conn.Close()

	stmt, err := conn.PrepareContext(ctx,
		`INSERT INTO audit_events(name) VALUES (?)`)
	if err != nil {
		return err
	}
	// Stmt 与 conn 绑定，必须早于 conn.Close 结束使用。
	defer stmt.Close()

	_, err = stmt.ExecContext(ctx, name)
	return err
}

这段代码的顺序很重要：先关闭 Stmt，再归还 Conn。如果把连接提前关闭，绑定它的语句就会进入不可用状态。固定连接也意味着连接池少了一条可调度资源，因此不能把这种写法当成普通重复写入的默认方案。

把关闭、上下文和错误放在同一条路径上

准备语句和执行语句都可能失败，错误处理不要只覆盖最常见的成功路径。初始化组件时，若 PrepareContext 失败，不要返回一个内部语句为空的对象；运行期间，ExecContext 或 QueryContext 的错误应直接交给上层决定重试、回滚或记录。

上下文的作用也要分清：PrepareContext 使用传入的上下文完成准备动作，ExecContext 使用自己的上下文控制本次执行。不要因为语句已经准备好，就把请求取消、超时和数据库执行生命周期混为一谈。

func (w *UserWriter) AddWithContext(ctx context.Context, name, email string) (err error) {
	if w == nil || w.stmt == nil {
		// 防止组件初始化失败后仍被调用，返回可识别的错误。
		return errors.New("user writer is not initialized")
	}
	_, err = w.stmt.ExecContext(ctx, name, email)
	return err
}

上面的示例需要额外导入 errors。生产代码中可以使用项目已有的错误类型，并在日志中记录操作名和请求标识；不要记录密码、令牌或完整的敏感参数。

发布前用这张清单检查

常见问题

sql.Stmt 能被多个 goroutine 同时使用吗？

从 DB 准备的 Stmt 可以并发使用；但并发安全不等于可以忽略关闭和连接生命周期。拥有它的组件仍应在退出阶段统一调用 Close。

为什么不用每次调用都 db.Prepare？

重复调用会把准备语句和释放语句的开销带进每次请求。对于 SQL 文本稳定、执行次数较多的场景，把语句作为组件依赖复用更合适；低频一次性 SQL 仍可直接使用 ExecContext。

Conn.PrepareContext 一定比 DB.PrepareContext 快吗？

不能这样概括。前者解决的是固定连接和会话状态需求，同时会占用一条保留连接；后者交给连接池调度，更适合普通业务。应根据连接绑定需求选择，而不是只按“预编译”三个字判断。

总结：DB.PrepareContext 适合让连接池管理并复用预编译语句，Conn.PrepareContext 适合必须固定到单条连接的会话操作。把 Stmt.Close、Conn.Close、上下文和错误处理纳入同一条生命周期路径，才能既复用 SQL，又不把连接池资源变成隐性常驻状态。