Go database/sql 连接池满时怎样区分等待和超时

Go database/sql 连接池满时，等待是获取连接暂时无法完成的状态，超时是上下文预算耗尽后的结果；二者不是同一个指标。要判断一次请求是否卡在池前，应结合获取连接阶段的记录与 DB.Stats 的等待增量。单独看到 context deadline exceeded，不能证明连接池已满，也不能证明 SQL 已在数据库上执行。

官方地址：https://go.dev/。下面围绕一个用于解释的接口排障场景展开，不将示例时间线或代码当成真实事故和压测结果。范围仅限 MaxOpenConns、获取连接等待与上下文超时。

接口超时只是现象，先保留阶段证据

设想某接口在并发请求增加后延迟升高，错误日志出现超时。第一反应若是把 MaxOpenConns 翻倍，就已经跳过了关键判断：请求是否拿到了连接？持有连接多久？同一个 DB 上是否确实出现了等待？可能的占用原因和处理方向并不相同。

先保留请求关联标识、调用开始与结束、错误链和当时的上下文状态。把查询参数、凭据、完整连接串排除在日志之外。错误分类可通过 errors.Is 与 context.DeadlineExceeded 或 context.Canceled 比较，但驱动错误还需保留原值，不能所有超时都按同一种原因改写。

按请求顺序整理获取与执行记录

按逻辑顺序整理记录时，至少区分“尝试获取连接”“已经获取连接”“连接上的操作结束”。若第一段返回错误、根本没有进入操作回调，那么本次诊断代码没有发出回调中的 SQL；不过获取连接自身仍可能涉及新建连接或会话准备，不等于纯粹排队。

若已拿到连接，之后才返回超时，说明不能把这段失败归为“这次仍在等池里的连接”。继续看操作、驱动与上下文交互；本文不据此推断数据库内部具体阻塞。一个端到端耗时只能说明总预算消耗，无法分离连接等待与操作时间。

什么条件下连接池会进入等待

sql.DB 管理连接池，不是单条数据库连接。设置了正数 MaxOpenConns 后，当需要连接、没有空闲连接并且已达打开连接上限时，请求会进入等待。OpenConnections 达到上限本身不够：如果仍有 Idle，可能直接复用；采样值也只是一个瞬间状态。

DBStats 中 WaitCount 是累计等待次数，不是当前排队请求数；WaitDuration 是累计等待时长，不是某次 SQL 的耗时。应观察同一 DB、同一进程生命周期内的时间窗口增量，结合 InUse、Idle 与 MaxOpenConnections。进程重启或更换 DB 对象后，不能把前后的累计值直接相减。

等待不一定以超时结束：其他使用者归还连接后，本次可能成功继续。反过来，传入时上下文已经到期，也可能立即失败，尚未经历池满等待。上下文取消和连接归还接近发生时，也不应仅根据单个瞬间采样推断精确调度顺序。

用分阶段计时缩小故障范围

通常优先直接用 DB 的查询接口，不必为了计时永久改成专用连接。确实需要分离“获取”和“持有后的操作”时，可在有界诊断入口使用以下封装。它不包含驱动注册或连接配置，调用者传入已有 DB、非 nil logger 和同步回调；errors.Join 要求 Go 1.20 或更新版本。

package dbprobe

import (
    "context"
    "database/sql"
    "errors"
    "fmt"
    "log"
    "time"
)

// Observe 显式区分获取连接与持有连接后的操作；仅作有界诊断接入。
func Observe(ctx context.Context, db *sql.DB, logger *log.Logger,
    work func(context.Context, *sql.Conn) error) (err error) {
    before := db.Stats()
    start := time.Now()
    conn, acquireErr := db.Conn(ctx)
    acquireTime := time.Since(start)
    after := db.Stats()

    // 池统计是共享累计值，差值可能包含同时间段的其他请求。
    logger.Printf("phase=acquire elapsed=%s in_use=%d idle=%d max=%d wait_delta=%d duration_delta=%s",
        acquireTime, after.InUse, after.Idle, after.MaxOpenConnections,
        after.WaitCount-before.WaitCount, after.WaitDuration-before.WaitDuration)
    if acquireErr != nil {
        return fmt.Errorf("获取连接失败: %w", acquireErr)
    }
    defer func() {
        // 必须归还专用连接，清理失败不能伪装成操作成功。
        if closeErr := conn.Close(); closeErr != nil {
            err = errors.Join(err, fmt.Errorf("归还连接失败: %w", closeErr))
        }
    }()

    start = time.Now()
    err = work(ctx, conn) // 回调使用同一预算；必须在返回前关闭自身结果集。
    logger.Printf("phase=operation elapsed=%s err=%v", time.Since(start), err)
    if err != nil {
        return fmt.Errorf("连接获取后的操作失败: %w", err)
    }
    return nil
}

这里 acquire elapsed 是 DB.Conn 总耗时，可能包含排队、新建连接或会话准备，不能命名为精确 pool_wait_ms。统计差值则属于整个共享池，并发调用时可能来自其他请求。它们用于互相印证，不是把池级总量精确分摊到某一请求的工具。

回调必须使用传入的 conn，不能拿到专用连接后又调用 db.QueryContext 另取一条；上限较小时，这种嵌套获取会制造新的等待。结果集应在回调返回前关闭，专用 Conn 则由封装负责归还。该实现刻意扩大了显式持有范围，诊断结束后应评估是否继续保留。

先缩短占用，再决定是否调大上限

若窗口里等待持续增加且连接长期被占用，优先检查结果集、事务和专用连接是否按时结束，以及是否在持有连接期间做了不必要的外部工作。不要只延长超时，让请求在更长时间里积压。限制进入数据库路径的并发，也是控制等待规模的一种方式。

若考虑调大 MaxOpenConns，应同时评估数据库可承受的并行量以及所有服务实例的总预算，而不是只看本进程上限。更多连接可能减轻本地排队，也可能把压力转移到数据库；等待下降不是吞吐和稳定性必然提升的证明。

上下文预算需覆盖实际调用链。同一上下文用于获取和操作时，前面消耗越多，留给后面的时间越少。若单独设置获取预算，拿到 Conn 后应使用仍有效的操作上下文，并在所有路径归还 Conn；不能继续拿已经取消的获取上下文去执行，也不能丢掉上游截止时间创建无界工作。

把等待与超时分别纳入复盘

WaitCount 除以请求数就是超时率吗？

不是。一次等待可能成功取得连接，累计等待次数也不等于超时次数；超时率需要按请求结果独立统计。

WaitDuration 增量除以 WaitCount 增量能代表每个请求的等待吗？

最多作为窗口级粗略参考。跨窗口的在途等待、并发与累计记账时点都会影响对应关系，不能当作单请求分位延迟。

没有设置正数上限就没有超时吗？

不是。无上限不代表连接建立和操作无限快，上下文也可能在其他阶段到期。不能通过取消连接限制来替代容量管理。

复盘结论应把证据和推断分开写：等待发生在哪个池、哪个窗口，具体请求失败在哪个阶段，采取什么措施缩短了持有时间。本文没有给出虚构的修复提升比例，也不把一次超时包装成已确认的数据库故障。

参考：Go 连接管理指南、DBStats 与连接接口、database/sql 获取连接实现。