Go问答：database/sql StmtContext 让预编译语句继承请求上下文的用法与边界

我在把数据库查询接到 HTTP 请求时，最容易误读的地方就是 Tx.StmtContext：它能把已经准备好的语句放进当前事务，但它传入的 Context 不是“以后每次执行都自动继承的超时开关”。真正控制一次查询或更新是否响应取消信号的，是 QueryContext、QueryRowContext 或 ExecContext 收到的 Context。

实用的组合是：准备阶段用 PrepareContext，事务绑定阶段用 Tx.StmtContext，每次执行阶段重新传入请求上下文。这样既能复用预编译语句，也不会把某一次请求的 deadline 错当成全局状态。

先分清三个 Context 的职责

PrepareContext 创建预编译语句时使用 Context；Tx.StmtContext 把已有语句转换为事务专用语句时也使用 Context。两者都不意味着后续执行会永久绑定这次请求的 Context。没有特别原因时，执行阶段使用 stmt.QueryContext(ctx, ...) 或 stmt.ExecContext(ctx, ...)，不要退回不带 Context 的方法。

准备可复用的 sql.Stmt

把准备动作放在组件初始化或连接管理层，执行动作留在请求函数里。准备 Context 只负责让准备过程有边界，准备成功后要由创建方负责关闭语句。

func prepareUserQuery(ctx context.Context, db *sql.DB) (*sql.Stmt, error) {
	// 准备阶段设置独立超时，避免驱动迟迟不返回。
	prepareCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
	defer cancel()

	stmt, err := db.PrepareContext(prepareCtx,
		"SELECT name FROM users WHERE id = ?")
	if err != nil {
		// 准备失败时没有可关闭的 Stmt，直接把驱动错误交给上层。
		return nil, err
	}
	return stmt, nil
}

func queryUser(ctx context.Context, stmt *sql.Stmt, id int64) (string, error) {
	// 每次执行都接收本次请求的 ctx，取消和 deadline 才能生效。
	var name string
	err := stmt.QueryRowContext(ctx, id).Scan(&name)
	if err != nil {
		return "", err
	}
	return name, nil
}

// 初始化完成后由拥有者在组件退出时执行：defer stmt.Close()

上面的关键不是把 ctx 存进 Stmt，而是让它沿着每一次执行调用传入。请求结束后，即使同一个语句仍会被下一次请求复用，也不会携带已经过期的 deadline。

按请求传递超时和取消信号

HTTP handler 通常可以直接使用请求 Context，再按数据库操作补一个更短的超时。查询可能返回多行时，要在循环结束后检查 rows.Err()，并确保 Rows.Close 被调用；如果驱动在取消后返回的是 context.Canceled 或 context.DeadlineExceeded，应把它和 SQL 语法、连接故障分开记录。

一个简单判断表如下：

在事务中使用 Tx.StmtContext

已有的 *sql.Stmt 可以通过 tx.StmtContext(ctx, stmt) 得到事务范围内的语句。这里的 ctx 负责绑定阶段；真正执行更新时仍使用 txStmt.ExecContext(requestCtx, ...)。事务是成功提交还是回滚，也必须由调用方明确处理。

func updateName(ctx context.Context, db *sql.DB, stmt *sql.Stmt, id int64, name string) error {
	// BeginTx 的 ctx 被取消时，database/sql 会结束这次事务；仍要显式处理错误。
	tx, err := db.BeginTx(ctx, nil)
	if err != nil {
		return err
	}

	txStmt := tx.StmtContext(ctx, stmt)
	// 事务语句随事务结束，不把它当成全局 Stmt 长期保存。
	_, err = txStmt.ExecContext(ctx, name, id)
	if err != nil {
		// 更新失败时回滚；回滚错误不能覆盖原始执行错误。
		_ = tx.Rollback()
		return err
	}
	if err := tx.Commit(); err != nil {
		return err
	}
	return nil
}

用错误和清理动作验收

先确认每一层的拥有者：长期复用的 Stmt 在组件退出时关闭；多行结果的 Rows 在当前函数结束前关闭；事务执行失败回滚，成功才提交。不要只看 Scan 的返回值就认为查询完整，还要检查迭代错误。

• 超时：优先判断 errors.Is(err, context.DeadlineExceeded)。
• 主动取消：判断 errors.Is(err, context.Canceled)，通常不当成业务失败重试。
• 驱动错误：保留原始错误和操作名，区分准备、执行、提交三个阶段。
• 无 Context 方法：Query、Exec 会使用后台 Context，无法表达当前请求的取消边界。

相关问题

StmtContext 会让语句永久绑定某个请求吗？

不会。它返回事务专用语句，传入的 Context 用于绑定过程；每次执行仍应传入当前请求 Context。

普通查询应该用 QueryContext 还是 QueryRowContext？

确定最多一行时用 QueryRowContext；需要遍历多行时用 QueryContext，并在结束时检查 Rows.Err。

请求被取消后还要 Rollback 吗？

要。取消通常会让事务无法继续，但代码仍应显式调用 Rollback 并处理提交或回滚路径。

Stmt.Close 会关闭数据库连接吗？

不会。它只释放预编译语句本身；数据库连接池由 db.Close 在整个 DB 生命周期结束时统一关闭。