Go sql.DB.Stats 中 WaitCount 持续增长说明什么

如果 Go 服务里的 sql.DB.Stats().WaitCount 一直增加，最准确的解释是：有请求曾经因为暂时拿不到可用数据库连接而等待过。它不是“当前有多少请求排队”，也不是数据库已经故障；这是从连接池统计开始累计的等待次数。要判断问题是否严重，还要同时看 WaitDuration、InUse、OpenConnections 和 MaxOpenConnections。

我排查这类指标时，先把它当作一个累计计数器，再用相邻采样的增量还原时间窗口内的等待情况。这样可以避免看到一个很大的历史值就贸然调大连接池。

先区分 WaitCount 和当前排队状态

Go 官方文档把 DBStats.WaitCount 定义为“等待过连接的总次数”，WaitDuration 是“阻塞等待新连接的总时间”。两者从 DB 创建后持续累计，服务重启后才会重新开始统计。因此，单看绝对值没有意义，重点是窗口增量。

例如两个采样点相隔 30 秒，WaitCount 增加 600，WaitDuration 增加 12 秒，粗略平均每次等待约 20 毫秒。这个平均值不是百分位延迟，但足以帮助判断“很多次短等待”还是“少数几次长等待”。

用一组快照确认是否撞到连接上限

把统计读取放到已有的指标采集协程中即可，不需要为了排查给每条 SQL 加日志。下面的示例只输出增量，避免把累计值误当成当前值：

package main

import (
    "database/sql"
    "log"
    "time"
)

type poolSample struct {
    at           time.Time
    waitCount    int64
    waitDuration time.Duration
}

func samplePool(db *sql.DB, previous poolSample) poolSample {
    // Stats 返回连接池快照；WaitCount 和 WaitDuration 都是累计计数。
    stats := db.Stats()
    now := poolSample{
        at:           time.Now(),
        waitCount:    stats.WaitCount,
        waitDuration: stats.WaitDuration,
    }
    elapsed := now.at.Sub(previous.at)
    if previous.at.IsZero() {
        // 首次采样只建立基线，不计算虚假的窗口增量。
        return now
    }
    deltaCount := now.waitCount - previous.waitCount
    deltaDuration := now.waitDuration - previous.waitDuration
    log.Printf("db_pool window=%s wait_count=%d wait_duration=%s in_use=%d open=%d max_open=%d",
        elapsed, deltaCount, deltaDuration, stats.InUse, stats.OpenConnections, stats.MaxOpenConnections)
    return now
}

判断“是否撞到上限”时，优先看 MaxOpenConnections > 0 且 OpenConnections 长时间接近它，同时 InUse 也接近上限、等待增量持续出现。若 MaxOpenConnections 为 0，官方语义是不限最大打开连接数，此时仍有等待就要继续查连接建立、驱动行为、事务持有时间或数据库端响应。

图：把 DB、DBStats、连接池状态和窗口增量放在同一张图里，避免把 WaitCount 的历史累计含义误读成实时队列。

持续增长最常见的四条线索

连接池上限过小。 并发请求经常同时需要连接，InUse 接近 MaxOpenConnections，而每次等待很短。这里需要结合数据库允许的最大连接数和实例数量计算总连接预算，不能只在 Go 侧加大。

事务或 Rows 持有连接过久。 查询结果没有及时关闭、事务跨越网络调用，都会让连接迟迟不能回池。代码中应让 rows.Close()、rows.Err() 和事务回滚/提交路径清晰可见。

数据库响应变慢。 这时 WaitCount 可能只是结果，真正的根因在慢 SQL、锁等待或数据库资源不足。要把请求耗时、SQL 观测和数据库端指标放到同一时间窗口比较。

突发并发或连接失效重建。 流量尖峰、连接生命周期集中到期、网络抖动可能造成短时等待。若 OpenConnections 没有稳定贴近上限，却出现等待增量，应优先查看连接建立错误和驱动日志。

处理方式：先缩短持有时间，再调整参数

每个数据库操作都应有上下文边界，避免请求无限期占住连接：

func loadUser(ctx context.Context, db *sql.DB, id int64) (string, error) {
    // 超时保护等待连接和查询执行；具体时长按业务 SLA 调整。
    queryCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()

    var name string
    err := db.QueryRowContext(queryCtx,
        "select name from users where id = ?", id,
    ).Scan(&name)
    // QueryRowContext 的 Scan 结束后，连接可以回到连接池。
    return name, err
}

参数调整应遵循“数据库容量、应用实例数、单请求持有时间”三者一起看。SetMaxOpenConns 太小会制造排队，太大则可能把数据库推入连接耗尽；SetMaxIdleConns 影响突发流量后的复用，SetConnMaxLifetime 和 SetConnMaxIdleTime 则用于控制连接生命周期。它们都不是 WaitCount 的直接清零开关。

图：把连接池配置、请求资源持有和数据库容量分成三个边界，排查时应找证据对应的边界，而不是只改一个数字。

最小验证口径

修复后至少连续观察几个相同长度的窗口：窗口内 WaitCount 增量是否下降，WaitDuration 增量是否同步下降，平均等待时间是否仍有长尾；同时确认 InUse / MaxOpenConnections 没有长期满载，业务请求耗时和数据库端慢查询没有被掩盖。

可以把判断写成一张小表：

因此，Go sql.DB.Stats 中的 WaitCount 持续增长说明连接获取曾经出现过等待，但严重程度要由窗口增量和等待时长决定。先建立快照基线，再定位连接上限、资源释放或数据库响应问题，最后才调整连接池参数。

相关问题

WaitCount 会自动归零吗？

它是累计统计，通常不会按时间窗口自动归零。监控端应保存上一次采样，计算差值。

把 MaxOpenConns 调大就能解决吗？

只有在数据库还有容量、应用确实被连接上限限制时才可能有效；如果连接被慢查询或事务长期占用，盲目增大反而会放大数据库压力。

WaitDuration 能代替 SQL 慢查询监控吗？

不能。它只覆盖等待连接的阻塞时长，不包含拿到连接后的完整 SQL 执行时间。