Go database/sql.DB.Stats 怎么看连接池是否出现等待

判断 Go 的 SQL 连接池有没有出现等待，不能只盯着某一次 InUse 或 Idle。更可靠的做法是先看当前池状态，再把两次 DB.Stats() 快照中的 WaitCount 与 WaitDuration 做差：等待次数增量大于 0，说明窗口内确实有人等过连接；等待时间增量再除以等待次数增量，才能得到这个窗口的平均等待时长。

先看懂 DBStats 的四组连接池字段

db.Stats() 返回一个 sql.DBStats 值，它把连接池的容量、当前状态和累计事件放在同一份快照里。最先看这几项：MaxOpenConnections 表示允许打开的最大连接数；OpenConnections 表示已经建立的连接总数；InUse 表示当前被使用的连接；Idle 表示当前空闲连接。

func samplePool(db *sql.DB) sql.DBStats {
	// Stats 返回当前时刻的连接池快照，不会替你等待一个完整监控周期。
	return db.Stats()
}

func printPoolState(db *sql.DB) {
	s := samplePool(db)
	// 这些字段用于描述当前容量和连接分布，不是时间窗口指标。
	fmt.Printf("max=%d open=%d inUse=%d idle=%d\\n",
		s.MaxOpenConnections, s.OpenConnections, s.InUse, s.Idle)
}

如果 OpenConnections 已经贴近正数的 MaxOpenConnections，同时 Idle 很少，说明池的可用余量有限；如果 OpenConnections 没有达到上限，却仍然出现等待，就不能只凭这一行快照下结论，还要结合采样窗口和连接生命周期继续看。

WaitCount 和 WaitDuration 为什么要看累计量

官方定义中，WaitCount 是等待连接的总次数，WaitDuration 是等待新连接时累计阻塞的总时间。它们不是“现在有多少请求正在排队”的实时队列长度，而是从连接池开始工作后不断累加的计数器。

因此，单次看到 WaitCount=1200 只能说明历史上累计发生过 1200 次等待，不能说明最近一分钟是否拥堵。相反，如果两次采样之间 WaitCount 从 1200 变成 1240，就能确认这个窗口新增了 40 次等待。

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

func takeSample(db *sql.DB) poolSample {
	s := db.Stats()
	// 保存累计字段和采样时间，下一次采样时才能计算窗口增量。
	return poolSample{
		at:           time.Now(),
		waitCount:    s.WaitCount,
		waitDuration: s.WaitDuration,
	}
}

用两次采样计算等待窗口

监控时可以每隔固定时间获取一次快照。设前一次为 prev，后一次为 curr，窗口内等待次数为 curr.WaitCount - prev.WaitCount，窗口内等待时间为 curr.WaitDuration - prev.WaitDuration。只有等待次数增量大于零时，平均等待时间才有意义。

func waitWindow(prev, curr poolSample) (int64, time.Duration, time.Duration, bool) {
	countDelta := curr.waitCount - prev.waitCount
	durationDelta := curr.waitDuration - prev.waitDuration
	if countDelta 

例如窗口开始时 WaitCount=1200、WaitDuration=18s，窗口结束时分别为 1240 和 20s，那么这个窗口新增 40 次等待、累计新增等待 2 秒，平均每次等待约 50 毫秒。这里的数值只是计算示例，不是某次线上运行结果。

看到等待增长后，先判断是不是连接池触顶

窗口内 WaitCount 增长，说明部分操作没有立即拿到连接，但它没有直接告诉你根因。先把窗口前后的 InUse、Idle、OpenConnections 和 MaxOpenConnections 放在一起看：

不要把“连接池出现等待”直接写成“数据库慢”。连接池等待只说明应用侧在获取连接时发生过阻塞；数据库执行时间、网络延迟、事务锁等待等问题，需要用数据库和请求层面的独立指标判断。

把 Stats 采样做成可比较的指标

生产监控中建议同时记录采样时间、池状态和窗口增量。累计计数器适合用速率或差值展示，瞬时字段适合看当前水位，两者不要混成同一类图表。

func reportWindow(db *sql.DB, prev poolSample) poolSample {
	curr := takeSample(db)
	countDelta, durationDelta, average, ok := waitWindow(prev, curr)
	if ok {
		// 这里输出的是一个采样窗口，便于和并发量、请求耗时对齐比较。
		fmt.Printf("window=%s waits=%d wait_duration=%s avg_wait=%s\\n",
			curr.at.Sub(prev.at), countDelta, durationDelta, average)
	} else {
		// 没有新增等待时保留明确的零事件，而不是把累计总数当成窗口值。
		fmt.Printf("window=%s waits=0\\n", curr.at.Sub(prev.at))
	}
	return curr
}

如果应用重启或监控进程重新建立基线，第一次采样不要拿来计算增量；先保存为 prev，下一次采样再计算。若计数器出现回退，通常应视为进程重启、采集切换或数据源更换，重新建立窗口。

常见问题

WaitCount 大于零是不是说明现在还有请求在排队？

不是。它是累计等待次数。要判断当前窗口是否发生等待，应比较两次采样的差值；它也不能直接表示当前排队人数。

WaitDuration 能不能直接除以 WaitCount？

可以得到进程启动以来的历史平均等待时间，但排查最近拥堵时应优先使用两个快照的增量相除，否则旧流量会稀释近期问题。

把 MaxOpenConnections 调大就能消除等待吗？

不一定。上限过小可能导致排队，但增大上限也会增加数据库并发压力；还要确认连接是否被长事务、未关闭的 Rows 或过大的请求并发占用。

Idle 很少是不是一定有问题？

不是。低 Idle 可能只是当前流量较高。只有当它与连接上限接近、等待增量持续增长等信号同时出现时，才更像连接池压力。

总结起来，DB.Stats() 的正确读法是“瞬时状态看水位，累计字段看增量”。先用 InUse、Idle 和 OpenConnections 判断池的当前形状，再用 WaitCount、WaitDuration 的窗口差值确认是否真的发生等待，最后结合连接持有时间和数据库侧指标决定调参还是继续排查。