Go database/sql DB.Stats MaxIdleClosed 为什么持续增加

如果你看到 DB.Stats().MaxIdleClosed 持续增加，先不要把它直接判断成连接泄漏。这个字段统计的是：因为 SetMaxIdleConns 限制而被关闭的连接累计数量。连接回收到池里时，如果空闲连接已经超过允许保留的上限，多出来的连接会被关闭，计数随之增加。

官方文档：https://pkg.go.dev/database/sql#DBStats

MaxIdleClosed 是累计计数，不是当前关闭动作；它增长说明连接池曾经因为“空闲数量上限”回收过连接。要判断是否配置不合理，还要同时看 Idle、OpenConnections、WaitCount，以及另外两个关闭计数。

MaxIdleClosed 到底统计了什么

DB.Stats() 返回一个 DBStats 快照。它同时包含两类信息：连接池此刻的状态，以及从连接池创建以来不断累加的计数。

瞬时状态主要是 OpenConnections、InUse 和 Idle。例如，OpenConnections 是当前已建立连接总数，InUse 是正在使用的连接数，Idle 是暂时回到池里的连接数。它们会随请求并发变化。

MaxIdleClosed、MaxIdleTimeClosed 和 MaxLifetimeClosed 则是累计值。应用运行越久，它们只会保持不变或增加，所以不能用“当前值大于零”直接判定故障。

为什么空闲连接会触发这个计数

SetMaxIdleConns(n) 设置的是空闲连接池最多保留多少条连接，不是整个数据库连接数的硬上限。当一批请求结束、多个连接陆续归还时，连接池可能短时间拥有比 n 更多的空闲连接。超出的部分没有必要继续保留，就会被关闭，并累加 MaxIdleClosed。

例如下面的配置允许最多 20 条打开连接，但只保留 4 条空闲连接：

db.SetMaxOpenConns(20)
db.SetMaxIdleConns(4)

// 统计值只用于观测，不改变连接池配置。
func snapshot(db *sql.DB) sql.DBStats {
    return db.Stats()
}

当并发峰值把打开连接数推高，峰值结束后可能有 20 条连接一起归还。连接池最多留下 4 条，其余连接会让 MaxIdleClosed 增加。这个过程本身是连接池的正常回收策略，并不表示业务代码忘记关闭连接。

另一种常见触发方式是运行中把 MaxIdleConns 调小。官方实现会把当前空闲连接裁剪到新的上限，裁剪数量也会计入该字段。因此，动态调参后看到一次明显增长，并不奇怪。

三个关闭计数不要混在一起

排查时最容易犯的错误，是看到“连接被关闭”就只盯着 MaxIdleClosed。三个字段对应三种不同的控制条件：

例如只有 MaxIdleTimeClosed 增加，通常应先看空闲时长配置；只有 MaxLifetimeClosed 增加，则更接近连接生命周期轮换。三个字段同时增加，也可能是连接池配置本来就同时设置了三种回收条件。

用 DBStats 快照判断是回收还是压力

不要只记录一个累计值。更有用的做法是定时保存相邻两次快照，计算累计字段的增量，同时把连接池状态一起记录下来。下面的函数只读取统计信息，不执行查询，也不会改变连接池行为。

package poolmetrics

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

// LogDelta 对比两个时间点的 DBStats，区分状态和累计计数。
func LogDelta(db *sql.DB, before, after sql.DBStats, at time.Time) {
    // OpenConnections、InUse、Idle 是快照，不应拿累计差值解释。
    log.Printf("at=%s open=%d in_use=%d idle=%d wait_count_delta=%d wait_duration_delta=%s",
        at.Format(time.RFC3339),
        after.OpenConnections,
        after.InUse,
        after.Idle,
        after.WaitCount-before.WaitCount,
        after.WaitDuration-before.WaitDuration,
    )

    // 三个关闭计数的增量分别对应三种回收原因。
    log.Printf("max_idle_closed_delta=%d max_idle_time_closed_delta=%d max_lifetime_closed_delta=%d",
        after.MaxIdleClosed-before.MaxIdleClosed,
        after.MaxIdleTimeClosed-before.MaxIdleTimeClosed,
        after.MaxLifetimeClosed-before.MaxLifetimeClosed,
    )
}

如果某个时间窗口内 MaxIdleClosed 增量很大，但 WaitCount 没有增加、InUse 也没有长期贴近 MaxOpenConnections，更像是峰值结束后的空闲数量裁剪，而不是连接池被压满。

反过来，如果 WaitCount 和 WaitDuration 同步增加，且 InUse 长时间接近 MaxOpenConnections，说明调用方在等待连接。此时不能因为 MaxIdleClosed 也增长，就把根因归到“关闭太多”；需要先检查并发、查询耗时和池上限。

配置时怎样减少无意义的空闲回收

调整目标不是让 MaxIdleClosed 永远为零，而是让保留的空闲连接与业务负载匹配：

• 有明显并发峰值、峰谷切换频繁时，不要把 MaxIdleConns 设得远低于稳定并发；否则每次峰值后都会建立又关闭一批连接。
• 连接建立成本较高时，可以适当提高空闲上限，但同时关注数据库服务端的连接配额。
• 流量长时间低迷时，可以用 SetConnMaxIdleTime 清理长期不用的连接，不要把它和空闲数量上限混为一谈。
• 需要定期轮换连接时使用 SetConnMaxLifetime，并通过 MaxLifetimeClosed 观察轮换量。

// 下面的数值只是配置示例，应按服务并发和数据库配额调整。
db.SetMaxOpenConns(20)                  // 限制同时打开的连接总数
db.SetMaxIdleConns(8)                   // 为常态并发保留一组空闲连接
db.SetConnMaxIdleTime(10 * time.Minute) // 清理长期空闲连接
db.SetConnMaxLifetime(30 * time.Minute) // 定期轮换连接，避免无限复用

示例中的四个参数并不是固定答案。尤其要注意：SetMaxIdleConns 影响的是空闲数量，SetConnMaxIdleTime 影响的是空闲时长，SetConnMaxLifetime 影响的是连接年龄。先根据计数增量确认是哪一类回收，再改对应参数。

排查 MaxIdleClosed 时记住这五点

1. 把它当累计计数，记录窗口增量，不要把当前值当实时连接数。
2. 同时记录 OpenConnections、InUse 和 Idle，确认连接池是否在峰值后回落。
3. 把 MaxIdleClosed、MaxIdleTimeClosed、MaxLifetimeClosed 分开看。
4. 用 WaitCount 和 WaitDuration 判断是否存在连接等待，避免把池压力误认为回收问题。
5. 只有当回收频率与连接建立成本、数据库配额或延迟目标不匹配时，才需要调整配置。

因此，“MaxIdleClosed 为什么持续增加”的核心答案是：只要连接归还时空闲数量超过 SetMaxIdleConns，它就会继续累计。判断是否需要修复，要把这个计数放回连接池峰值、等待指标和另外两种关闭原因中一起解释。

相关问题

MaxIdleClosed 增加是不是连接泄漏？

不是。它描述的是连接池主动因空闲数量上限而关闭连接；连接泄漏更应结合长期增长的打开连接、未关闭的结果集或事务等证据判断。

把 MaxIdleConns 设得很大就不会关闭了吗？

不一定。空闲时间和连接生命周期仍可能关闭连接，数据库服务端也可能主动断开。应同时观察三个关闭计数与实际连接状态。

为什么 MaxIdleClosed 不变但连接仍然减少？

可能是空闲时间、生命周期、数据库端断开或应用显式关闭等其它原因。这个字段只覆盖 SetMaxIdleConns 导致的关闭。