Go 数据库请求超时后仍占连接：正确传递 Context 并确认取消生效

Go 服务里“请求已经超时，数据库连接却还在占用”并不罕见。最常见的原因是只在 HTTP 层设置了超时，查询函数继续使用 context.Background()，或者调用了不带 Context 的 Query。正确做法是从请求 Context 派生 queryCtx，把它传给 QueryContext，并在查询结束后关闭 Rows。这样上游取消和本地数据库超时才会沿调用链传下去。

先把请求超时边界传到 queryCtx

在 HTTP handler 中，r.Context() 会随着客户端断开而取消；数据库函数不应另起一个脱离请求的背景 Context。官方示例建议用 context.WithTimeout 派生子 Context，并在函数返回时调用 cancel 释放定时器等资源。

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

    var u User
    err := db.QueryRowContext(queryCtx,
        `SELECT id, name FROM users WHERE id = ?`, id,
    ).Scan(&u.ID, &u.Name)
    if err != nil {
        if errors.Is(queryCtx.Err(), context.DeadlineExceeded) {
            return User{}, fmt.Errorf("load user timeout: %w", err)
        }
        return User{}, err
    }
    return u, nil
}

这里的关键不是把 2 秒写死，而是让上游取消优先级自然传递。若请求只剩 300 毫秒，子 Context 不会凭空获得更多时间；在更复杂的调用链中，可先比较父级 deadline，再决定是否发起查询。

QueryContext 返回错误后还要检查 Rows

多行查询要同时处理“调用返回错误”和“遍历过程中出错”两条路径。Query 不接收 Context，不能承担超时取消；QueryContext 才把取消信号交给 database/sql 和底层驱动。

func listOrders(ctx context.Context, db *sql.DB, userID int64) ([]Order, error) {
    queryCtx, cancel := context.WithTimeout(ctx, 1500*time.Millisecond)
    defer cancel()

    rows, err := db.QueryContext(queryCtx,
        `SELECT id, amount FROM orders WHERE user_id = ?`, userID,
    )
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    var result []Order
    for rows.Next() {
        var item Order
        if err := rows.Scan(&item.ID, &item.Amount); err != nil {
            return nil, err
        }
        result = append(result, item)
    }
    if err := rows.Err(); err != nil {
        return nil, err
    }
    return result, nil
}

取消发生在返回首批结果之后时，错误可能出现在 rows.Err()，而不是 QueryContext 的初始返回值。生产日志至少要记录查询耗时、queryCtx.Err()、返回错误和结果行数。

驱动和连接池决定取消能走多远

Context 取消是协作式信号，database/sql 能否让数据库侧尽快停止，还取决于驱动实现和数据库协议。事务中的每一条查询、预处理和提交操作都应传入同一个 ctx，不要只给第一条 SQL 设置超时。取消错误也不要无条件重试，否则超时请求可能立刻制造第二次查询。

可以周期性记录 db.Stats()，但不要把单次 InUse 偏高直接判定为泄漏。应按相同时间窗口对照请求数、查询耗时、连接池上限和数据库活动连接；如果 HTTP 已返回而数据库日志仍长时间执行，再检查驱动取消能力与服务器端 statement timeout。

用同一 trace_id 验证取消结果

排查时不要只看一条 504。给请求、数据库调用和驱动日志使用同一个 trace_id，至少记录四个时间点：请求取消、QueryContext 返回、Rows 关闭、连接池指标回落。若请求取消后很快返回，但数据库活动仍持续，说明 HTTP 层已经结束，数据库侧取消尚未完成或并未支持。

一个实用的验收清单是：超时后 errors.Is(queryCtx.Err(), context.DeadlineExceeded) 能成立；多行查询的 rows.Err() 不被忽略；Rows 一定关闭；DBStats.InUse 在稳定窗口内回落；取消错误不会触发无限重试。只有这些信号一致，才可以说“取消生效”。

常见问题

为什么请求超时了，SQL 还会继续执行？

通常是查询使用了 Background Context、调用了 Query，或驱动没有把取消信号映射到数据库协议。先确认 Context 是否一路传到 QueryContext。

WithTimeout 返回的 cancel 可以不调用吗？

不建议。即使查询提前结束，也应 defer cancel，及时释放派生 Context 关联的定时器和资源。

DBStats.InUse 一直高就是连接泄漏吗？

不一定。连接池会保留空闲连接；要结合 InUse、Idle、WaitCount、请求并发和数据库活动连接的时间序列判断。