Go 数据库超时返回后连接为何不回落：从 Context 传播排查 database/sql 取消链

Go 服务里最容易被忽略的一种超时，是 HTTP 请求已经返回了超时，但数据库查询仍然占着连接。根因通常不是“超时参数太小”，而是取消信号没有进入 database/sql：上层创建了 Context，下层却调用了不带 Context 的 Query，或者把它替换成了 context.Background()。

正确做法是以请求 Context 为父节点，用 context.WithTimeout 派生查询 Context，再把它传给 QueryContext、QueryRowContext 或 ExecContext；同时关闭结果集、检查 rows.Err，并确认所用驱动支持取消。调用方提前返回，不等于数据库服务端一定已经停止。

下面用一段最小写法说明边界。示例只依赖标准库接口，具体 SQL 驱动需要按项目实际替换。

把请求截止时间变成查询自己的 Context

请求处理器已经有了 r.Context()，不要重新从 context.Background() 开始。这样客户端断开、上游取消或服务端截止时间才能继续向下游传播。查询还可以有更短的局部预算：

func loadUser(r *http.Request, db *sql.DB, id int64) (string, error) {
    queryCtx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    var name string
    err := db.QueryRowContext(queryCtx,
        "SELECT name FROM users WHERE id = ?", id).Scan(&name)
    return name, err
}

这里的请求处理器、请求 Context、WithTimeout、查询 Context、QueryContext 和取消函数分别承担不同职责：请求 Context 负责继承外部取消，WithTimeout 负责收紧边界，取消函数负责回收派生 Context 资源。defer cancel() 不是可有可无的样板。

只通过 QueryContext 或 ExecContext 进入数据库

如果函数签名收到了 Context，就要把它一路传到真正执行 SQL 的那一层。查询用 QueryContext 或 QueryRowContext，写入用 ExecContext，事务则使用 BeginTx。不要出现“外层有超时、仓储层重新 Background”的断链。

func saveAudit(ctx context.Context, db *sql.DB, uid int64) error {
    _, err := db.ExecContext(ctx,
        "INSERT INTO audit_log(user_id) VALUES (?)", uid)
    return err
}

参数绑定仍然通过占位符完成，Context 只负责取消和截止时间。它不会替你修复慢 SQL、锁等待或连接池上限；这些是另一个性能问题。尤其要注意，database/sql 的官方文档说明：不支持 Context 取消的驱动，可能要等查询完成后才返回。

正确关闭结果集并区分取消错误

多行查询不能只写 for rows.Next() 就结束。拿到 rows 后立即安排关闭，并在遍历后检查 rows.Err()。请求截止时间到了，常见判断是 errors.Is(err, context.DeadlineExceeded)；客户端主动取消则可能是 context.Canceled。驱动也可能返回自己的包装错误，因此不要只比较字符串。

rows, err := db.QueryContext(queryCtx, query)
if err != nil { return err }
defer rows.Close()

for rows.Next() {
    // Scan 当前行
}
if err := rows.Err(); err != nil {
    switch {
    case errors.Is(err, context.DeadlineExceeded):
        return fmt.Errorf("query timeout: %w", err)
    case errors.Is(err, context.Canceled):
        return fmt.Errorf("request canceled: %w", err)
    default:
        return err
    }
}

rows.Close() 负责结果集资源边界，rows.Err() 负责把遍历期间发生的问题带回来。两者缺一不可。

用驱动能力和连接池指标确认边界

排查“超时后仍占连接”时按四个问题检查：第一，是否从请求 Context 派生了查询 Context；第二，SQL 是否走了带 Context 的方法；第三，结果集是否关闭且检查了 rows.Err；第四，当前驱动是否实现了取消。连接池可以用 db.Stats()观察 InUse、WaitCount 等趋势，但它们只能说明池的状态，不能证明数据库服务端已停止执行。

所以最终判断应分层：若调用方没有及时返回，先查 Context 传递；若 Go 侧已返回但连接长期不降，查 rows 关闭、驱动实现和数据库服务端会话；若只是等待数升高，再结合 SQL 慢、锁和连接池上限分析。这个边界比盲目把超时时间改成更大更可靠。

小结：以请求 Context 为父节点；用 WithTimeout 收紧查询预算；只调用 QueryContext/ExecContext；关闭 rows 并检查 rows.Err；最后把驱动取消能力和 DB.Stats 分开看。

相关问题

QueryContext 超时后数据库一定停止了吗？不一定。Go 调用方是否及时返回，还取决于驱动是否支持 Context 取消以及数据库服务端的中止机制。

为什么已经 defer cancel 还会占连接？cancel 只负责派生 Context 的生命周期；还要检查 rows.Close、驱动能力、服务端锁等待和连接池配置。

官方参考：Go：Canceling in-progress operations、database/sql、context。