Go context 超时后数据库查询仍未结束怎么办

之前线上踩过一个很典型的坑，给接口请求绑定的context到了超时时间返回错误之后，底层对应的数据库查询并没有跟着终止，一直占着连接不释放，并发上来没一会儿整个DB连接池就被耗满，后续新请求全部拿不到连接直接雪崩。碰到这类问题不用急，沿着调用链路逐层做适配就能彻底解决这类问题。

当context触发超时取消信号时，只要所用的Go数据库驱动完整兼容context规范，驱动层会自动向数据库服务端发送终止当前查询的指令，直接中断还在执行的未完成查询，避免连接被持续占用。

我第一次遇到这个现象，是给一个慢查询加上 3 秒超时后，接口已经返回了超时，但连接池的使用数还在上升。先记住一个判断：context 到期只代表取消信号已经发出，不等于数据库服务器和驱动一定立刻停止工作。如果查询仍未结束，应沿着“调用方法—database/sql—驱动—Rows 读取”逐层定位。

把 Query 换成 QueryContext 只是第一步；还要确认驱动实现了上下文查询，并在返回 Rows 后持续检查和关闭资源。

先把超时上下文传到真正的查询

最小写法是从请求上下文派生超时，并把同一个上下文传给 QueryContext。我习惯在函数入口就创建取消函数，避免后面某个分支忘记释放定时器。

ctx, cancel := context.WithTimeout(parent, 3*time.Second)
defer cancel() // 释放超时计时器，也让函数退出时取消派生上下文

rows, err := db.QueryContext(ctx, `SELECT id, status FROM jobs WHERE status = ?`, "ready")
if err != nil {
	// 超时、请求断开和数据库错误都在这里汇合，先返回，不继续使用 rows。
	return fmt.Errorf("query jobs: %w", err)
}
defer rows.Close() // 防止提前返回时连接和结果集仍被占用

for rows.Next() {
	var id int64
	var status string
	if err := rows.Scan(&id, &status); err != nil {
		return fmt.Errorf("scan job: %w", err)
	}
}
if err := rows.Err(); err != nil {
	// 驱动可能在 Next 阶段才报告取消或网络错误。
	return fmt.Errorf("iterate jobs: %w", err)
}
return nil

不要在这条链路里混入 db.Query、db.QueryRow 或使用 context.Background() 的封装。QueryRowContext 的错误通常延迟到 Scan 才返回，也要把 Scan 的错误当作查询结果的一部分处理。

为什么传了 context，查询仍然不马上停

关键不在 context.WithTimeout 本身，而在驱动有没有把取消继续落实。database/sql/driver 中的 QueryerContext 和 StmtQueryContext 都要求实现方在上下文取消时返回；如果连接没有这些接口，database/sql 会回退到旧的查询接口，或者走准备、执行、关闭的兼容路径。官方文档也明确提醒：不支持 context 取消的驱动，可能要等查询完成才返回。

因此排查时先看三件事：使用的驱动版本是否实现了对应 Context 接口；驱动是否把取消转换成数据库协议支持的取消动作；数据库端是否已经开始执行而不是卡在连接池等待、锁等待或网络读取。不能只凭 ctx.Err() == context.DeadlineExceeded 就断言服务器已经停止。

区分 QueryContext 阶段和 Rows 阶段

有些查询很快返回结果集，但真正的数据读取发生在 rows.Next()。这时日志只记录 QueryContext 返回时间，会误以为查询已结束。建议把“拿到 Rows”“读完 Rows”“关闭 Rows”分别记录，遇到超时同时打印 ctx.Err() 与 rows.Err()。

如果只读取第一行就返回，仍然要执行 rows.Close()；如果是单行查询，优先使用 QueryRowContext，并在 Scan 处处理错误。事务场景还要注意：事务由一个连接承载，查询取消后不要继续复用一个状态不确定的事务，应该按业务语义回滚或结束它。

用连接池现象反推真正原因

诊断代码可以只增加日志和连接池快照，不需要改变 SQL：

start := time.Now()
rows, err := db.QueryContext(ctx, query)
elapsed := time.Since(start)
stats := db.Stats()
log.Printf("query returned elapsed=%s ctx_err=%v in_use=%d wait=%d", elapsed, ctx.Err(), stats.InUse, stats.WaitCount)
if err != nil {
	return err // 记录到这里的错误，不把超时当成成功结果
}
defer rows.Close()
// 读取阶段也要检查 rows.Err，避免只看 QueryContext 的耗时。
for rows.Next() {
	// 这里仅处理当前业务需要的列。
}
return rows.Err()

如果 WaitCount 增长，问题可能先发生在连接池排队；如果 InUse 长时间不降，优先检查 Rows、事务和驱动取消能力。驱动确实不能取消时，应用层只能做到及时返回、限制并发、设置合理的连接池上限，并把数据库端慢查询和锁等待单独治理。不要在一个超时请求里继续等待“看起来应该很快结束”的查询，也不要在没有确认提交结果时重复执行有副作用的语句。

常见问题

超时后一定会返回 context.DeadlineExceeded 吗？不一定。具体错误由驱动和调用阶段决定，应同时保留错误链并检查 ctx.Err()。

只调用 cancel 能停止数据库服务器吗？不能保证。它会关闭 Go 侧的取消信号；服务器是否收到取消、何时停止，取决于驱动协议和数据库状态。

最后可以按这个顺序复盘：是否使用了 Context 方法、驱动是否实现 Context 接口、超时发生在取 Rows 还是迭代 Rows、Rows 和事务是否结束、连接池是否恢复。五项都能回答，通常就能解释“超时已返回但查询仍未结束”的真实原因。