Go sql.Stmt 关闭时如何处理正在执行的查询

如果多个 goroutine 正在使用同一个 sql.Stmt，不要用 stmt.Close() 取消其中的查询。Stmt 本身支持并发使用，Close 负责结束预编译语句的生命周期；真正控制查询超时或中止，应使用 QueryContext、ExecContext 配合 context.Context。服务停机时，推荐按“停止新任务→取消查询上下文→等待 worker→关闭 Stmt”的顺序收尾。

一句话判断：查询还在 Stmt.QueryContext 调用内部时，Close 会等待这段使用结束；查询已经返回 Rows 后，先关闭 Rows，再由整体生命周期负责关闭 Stmt。Close 不会替你给数据库发送取消信号。

先分清 Stmt、Rows 和 Context 的职责

sql.Stmt 是可复用的预编译语句句柄。用 DB.PrepareContext 创建的语句可以在多个 goroutine 中并发执行；它会随着 DB 的连接池工作。一次查询得到的 *sql.Rows 则代表具体结果集，可能占用连接或保持内部依赖，不能因为已经拿到了指针就认为资源全部释放。

三者的职责可以这样记：

• Context：控制单次查询的截止时间和取消信号。
• Rows：控制本次结果集的读取、关闭和迭代错误。
• Stmt：控制预编译语句是否还允许新的执行，以及最终资源释放。

因此，正在执行的查询收到取消信号后，通常会从 QueryContext、Rows.Next 或 Rows.Err 处返回错误；直接关闭 Stmt 只改变 Stmt 的生命周期，不应被当成业务取消 API。

查询返回 Rows 后为什么还要关闭它

对于返回多行数据的查询，成功拿到 Rows 后就登记关闭动作。遍历自然结束时，标准库可能自动关闭结果集，但显式 defer rows.Close() 能覆盖中途返回、扫描失败和上下文取消等路径。读取结束后还要调用 rows.Err()，因为 Next 返回 false 既可能表示正常结束，也可能表示驱动或网络错误。

func readUsers(ctx context.Context, stmt *sql.Stmt, teamID int64) error {
	// 成功创建 Rows 后立刻登记关闭，覆盖返回、扫描和取消等路径。
	rows, err := stmt.QueryContext(ctx, teamID)
	if err != nil {
		return fmt.Errorf("query users: %w", err)
	}
	defer rows.Close()

	for rows.Next() {
		var id int64
		var name string
		// Scan 错误要立即返回，避免把不完整结果当成成功数据。
		if err := rows.Scan(&id, &name); err != nil {
			return fmt.Errorf("scan user: %w", err)
		}
		// 这里处理 id 和 name；示例省略业务写入。
	}
	// Next 返回 false 后，用 Err 区分正常结束和查询中途失败。
	if err := rows.Err(); err != nil {
		return fmt.Errorf("iterate users: %w", err)
	}
	return nil
}

如果业务只需要一行，可以使用 QueryRowContext 并在 Scan 处处理错误；如果使用 QueryContext，则不要把 Rows 交给没有明确生命周期的后台 goroutine。

正在执行时调用 Close 会发生什么

实现上，Stmt 的查询和执行会持有读侧关闭锁，Close 需要获取独占关闭锁。因此，如果另一个 goroutine 还在 Stmt.QueryContext 或 Stmt.ExecContext 的关键阶段，调用 Close 可能阻塞到该操作释放读锁。这个等待是为了避免语句正在建立底层执行关系时被拆掉，并不表示 Close 在主动取消 SQL。

当查询已经返回 Rows 后，Stmt 的调用阶段已经返回，但结果集仍有自己的关闭过程。此时关闭 Stmt 不应替代 Rows.Close；尽快结束读取或显式关闭 Rows，才能让连接和相关语句依赖回到可回收状态。尤其是驱动不支持 Context 取消时，长查询仍可能继续到数据库端完成，不能用 Close 期待一个统一的即时中断效果。

需要中止一条正在运行的查询时，应该保存它自己的取消函数：

func runWithTimeout(parent context.Context, stmt *sql.Stmt, userID int64) error {
	// 超时只作用于这一次执行，不影响同一个 Stmt 的其他调用方。
	ctx, cancel := context.WithTimeout(parent, 2*time.Second)
	defer cancel()

	var name string
	err := stmt.QueryRowContext(ctx, userID).Scan(&name)
	if err != nil {
		// 生产代码可用 errors.Is 区分 context.DeadlineExceeded 等原因。
		return fmt.Errorf("load user %d: %w", userID, err)
	}
	log.Printf("user=%d name=%s", userID, name)
	return nil
}

这里的关键不是“关闭得更早”，而是把取消信号绑定到具体查询。一个共享 Stmt 可以继续服务其他调用方，而当前调用通过 Context 结束自己的等待。

优雅停机时推荐的关闭顺序

服务级 Stmt 通常在进程启动时创建，在进程退出或组件重载时关闭。并发收尾时先阻止新任务进入，再让正在执行的查询看到取消信号，等待所有 worker 退出，最后关闭 Stmt。下面的骨架把“查询取消”和“语句关闭”分成两个阶段：

func shutdown(ctx context.Context, cancel context.CancelFunc, stmt *sql.Stmt, wg *sync.WaitGroup) error {
	// 先广播取消，worker 应在自己的 QueryContext 中响应它。
	cancel()

	done := make(chan struct{})
	go func() {
		// 等待所有使用 Stmt 的 worker 结束，避免关闭顺序反过来。
		wg.Wait()
		close(done)
	}()

	select {
	case 

如果关闭阶段本身也有超时，应把“等待 worker 超时”和“Stmt.Close 返回错误”分别记录。不要在等待超时后强行把同一个 Stmt 交给另一个关闭流程，否则只会把生命周期问题变成竞态。事务内创建的 Stmt 还要注意：事务提交或回滚后，事务关联的语句会一并失效。

常见误区与排查清单

• 误区一：把 stmt.Close() 当作查询取消。排查时先确认调用方是否使用了 QueryContext 或 ExecContext。
• 误区二：只检查 Scan 错误，不检查 rows.Err()。网络断开、驱动返回错误可能出现在迭代阶段。
• 误区三：先关闭 Stmt，再等待 worker。把所有使用 Stmt 的任务纳入 WaitGroup，关闭前确认计数归零。
• 误区四：忽略驱动能力差异。标准库会传递 Context 取消，但驱动不支持时，查询可能要等数据库端完成。

最终可以用四个问题复盘：查询是否有独立 Context？Rows 是否在所有分支关闭？worker 是否在 Stmt.Close 前退出？关闭错误是否被记录并区分于查询取消错误？四项都能回答清楚，Stmt 的关闭时机通常就不会再成为隐蔽的并发问题。

相关问题

Stmt.Close 会让正在执行的 QueryContext 立刻返回吗？

不会。它主要关闭预编译语句并等待必要的关闭阶段，不承担统一的查询取消职责。要让查询尽快结束，应取消该查询使用的 Context，并继续处理 Rows 的关闭和错误。

所有 worker 都结束后还需要调用 Stmt.Close 吗？

需要。worker 结束只代表当前调用不再使用语句；显式关闭 Stmt 才能释放预编译语句相关资源。长期存活的 DB 组件可以在组件生命周期结束时统一执行一次。