Go database/sql 查询上下文取消后为什么还占连接

我第一次遇到这个现象，是把接口超时设成 2 秒后，日志已经打印了 context deadline exceeded，但 DB.Stats().InUse 还维持在高位。这里先给结论：QueryContext 只负责把取消信号带到数据库访问层，连接何时回到池里，还取决于驱动如何处理取消、结果集是否关闭，以及服务端协议是否已经收尾。它不是“超时一到，连接立刻归还”的硬保证。

官方资料入口：https://go.dev/doc/database/cancel-operations　https://pkg.go.dev/database/sql

先看清：占用连接不等于查询还在服务器上跑

*sql.DB 是连接池，不是某一条连接。查询开始时，池会把一个连接交给本次操作；只有结果集被关闭、事务结束，或驱动报告连接不可复用，连接才会进入空闲池或被丢弃。因此超时后短时间内 InUse 仍大于零，并不能直接判定为连接泄漏。

排查时把四个信号放到同一时间段：InUse 表示正在借出的连接，Idle 表示可复用连接，WaitCount 表示等待池连接的累计次数，WaitDuration 则反映等待代价。若取消后 InUse 最终下降，通常是清理有延迟；若长期不降，再去检查 Rows、事务和驱动。

QueryContext 能否中断，关键在驱动能力

标准库的 DB.QueryContext 会尝试把 Context 交给驱动的 QueryContext。官方 database/sql/driver 文档把 QueryerContext 定义为可选接口，并明确要求实现者在 Context 取消时返回。驱动没有这个接口时，标准库会退回不带 Context 的查询路径；它可以在调用前发现 Context 已取消，却无法替驱动中断一个已经阻塞的网络调用。

这就是“应用已经超时，连接仍占用”的第一类原因：应用层停止等待，不代表数据库服务器已经停止执行，也不代表驱动已经完成协议收尾。有些驱动会发送取消请求，有些会关闭底层连接来解除阻塞，具体行为必须看目标驱动文档和日志。

因此不要只改成 QueryContext 就结束迁移。至少要把驱动名称、版本、取消时返回的错误和 DB.Stats() 的变化一起记录。

Rows 要及时关，遍历结束要看 Err

只要查询返回了 *sql.Rows，就应该在确认没有错误后马上注册关闭动作。遍历提前结束、扫描失败或 Context 超时，都不能假设连接会按你的意图释放；Rows.Close 是明确的客户端收尾动作，Rows.Err 则告诉你遍历为何结束。

func loadNames(ctx context.Context, db *sql.DB) error {
	// 派生超时上下文，并保证函数退出时释放定时器资源。
	queryCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
	defer cancel()

	// QueryContext 成功后立刻注册 Close，覆盖提前返回的分支。
	rows, err := db.QueryContext(queryCtx, `SELECT id, name FROM users WHERE enabled = ?`, true)
	if err != nil {
		return err
	}
	defer rows.Close()

	for rows.Next() {
		var id int64
		var name string
		// Scan 失败时直接返回，defer 仍会关闭结果集。
		if err := rows.Scan(&id, &name); err != nil {
			return err
		}
	}
	// Next 返回 false 可能是正常结束，也可能是取消或网络错误。
	if err := rows.Err(); err != nil {
		return err
	}
	return nil
}

示例里的 defer rows.Close() 不是为了掩盖驱动问题，而是先把客户端能控制的生命周期做完整。生产代码还可以在查询前后采样 db.Stats()，确认取消之后 InUse 是否回落；不要用单次采样把短暂清理延迟误判成永久泄漏。

用四个检查点区分代码问题和驱动问题

如果代码使用了 db.Conn(ctx) 或显式 Tx，还要分别调用 Conn.Close、Rows.Close 和 Commit/Rollback。事务中的取消还会触发标准库回滚逻辑，但驱动和服务器完成回滚同样可能需要时间。

迁移时别漏掉这份清单

• 把请求或任务的 Context 传给 QueryContext、QueryRowContext 或 ExecContext。
• 每次创建超时 Context 都保留 defer cancel()。
• 拿到 Rows 后立刻 defer rows.Close()，循环后检查 rows.Err()。
• 记录驱动是否实现 Context 接口，并在集成测试里观察取消后的回池时间。
• 用 DB.Stats() 监控 InUse、Idle、WaitCount 和等待时长，不只盯一个指标。

相关问题

QueryContext 返回 context deadline exceeded，连接一定泄漏了吗？

不一定。它首先说明调用方的 Context 到期；连接是否回池要结合 Rows 是否关闭、驱动收尾和后续 Stats 变化判断。

只调用 rows.Next 到没有数据，还需要 Close 吗？

需要。完整遍历可能触发自动关闭，但显式 Close 能覆盖提前返回、Scan 失败和未来代码改动，成本很低。

把 MaxOpenConns 调大能解决取消后的占用吗？

只能延后池耗尽，不能修复驱动不响应取消或代码不关闭 Rows。先定位回池延迟，再决定池容量。