Go QueryContext 取消后连接为什么没有立即回到池中

很多 Go 服务在调用 QueryContext 超时后，马上查看连接池，发现 InUse 还没有下降，甚至 Idle 仍然是 0。这不一定表示取消失败。取消上下文只表示调用方不再等待，不能承诺底层连接瞬间回到池中。查询执行、结果集消费、驱动收尾和连接池统计是几个不同的时点。

优先确保 Rows 被关闭，再结合 DB.Stats() 判断连接是在等待结果、被驱动清理，还是已经被判定为坏连接而不会进入空闲池。

这篇只讨论标准库 database/sql 的生命周期，不把某个 MySQL、PostgreSQL 或 SQLite 驱动的取消实现当成统一行为。

先看 QueryContext 实际持有的连接

*sql.DB 是连接池句柄，不等于一条固定连接。调用 QueryContext 时，池先提供一条连接，返回的 *sql.Rows 会继续持有它；只有结果集读完、显式关闭，或内部清理完成后，连接才有机会归还。上下文取消与资源归还因此不是同一个事件。

最容易遗漏的是提前返回。下面的模板把关闭责任放在拿到 rows 后的第一时间，同时把取消错误和结果集错误分开记录：

ctx, cancel := context.WithTimeout(parent, 800*time.Millisecond)
defer cancel()

rows, err := db.QueryContext(ctx, query, userID)
if err != nil {
    // 查询尚未拿到结果集时，优先区分超时和驱动错误。
    return fmt.Errorf("query context: %w", err)
}
defer rows.Close() // 提前返回也要释放结果集持有的连接

for rows.Next() {
    var item Item
    // Scan 只负责取当前行，不能替代 rows.Close。
    if err := rows.Scan(&item.ID, &item.Name); err != nil {
        return fmt.Errorf("scan item: %w", err)
    }
    consume(item)
}
if err := rows.Err(); err != nil {
    // 取消可能在迭代阶段才表现为 Rows.Err。
    return fmt.Errorf("iterate rows: %w", err)
}
return nil

让取消信号传到驱动并释放结果集

database/sql 会把上下文交给驱动支持的调用路径。驱动实现了 driver.QueryerContext 时，可以直接看到取消信号；不支持时，标准库只能使用兼容路径，具体中断时机取决于驱动和底层连接。于是“ctx.Done() 已关闭”不等于“服务端语句、客户端读写和池状态都已完成收尾”。

还要注意两个边界：如果查询已经返回 Rows，取消发生在遍历期间，通常应从 rows.Err() 读取结果；如果驱动认定连接状态不再可靠，它可能把连接丢弃，而不是放回 Idle。这两种结果都可能是正确的资源保护动作。

用 DB.Stats 判断到底卡在哪里

不要只盯着一个数字。连续采样同一个 DB 的统计值，才能把“暂时未回池”和“连接永久被淘汰”区分开：

before := db.Stats()
err := runQuery(ctx, db)
after := db.Stats()

log.Printf("query err=%v in_use=%d idle=%d wait_count=%d open=%d",
    err, after.InUse, after.Idle, after.WaitCount, after.OpenConnections)
// InUse 反映采样瞬间的占用；它下降需要等结果集和驱动释放路径完成。
_ = before // 可在指标系统中记录差值，不要把一次采样当成最终结论。

常见误区与处理边界

第一，不要在拿到 Rows 前就写一个“取消后立刻回池”的断言；连接可能还在等待驱动返回。第二，不要把 SetMaxIdleConns 当成取消开关，它只影响连接归还后的保留数量。第三，若连接长期占用，应检查所有提前返回分支、是否把 Rows 传给了异步任务，以及驱动是否正确实现带上下文的接口。

一个可操作的判断顺序是：先确认 defer rows.Close() 已注册，再看 rows.Err()，随后连续记录 InUse、Idle、WaitCount 和 OpenConnections。只有在排除结果集未关闭和驱动收尾延迟后，才把问题升级为连接泄漏或池配置问题。

相关问题

QueryContext 返回错误后还要 Close Rows 吗？如果没有返回有效的 Rows，不需要关闭；如果已经拿到结果集，即使后续扫描失败，也应保证 Close 执行。

取消后连接一定会变成 Idle 吗？不一定。健康连接才可能进入空闲池，坏连接会被关闭；而且统计值反映的是采样瞬间，不是取消信号发出的瞬间。