Go sql.DB.SetConnMaxLifetime 的连接轮换配置方法

Go 的 sql.DB 是连接池，不是某一条固定连接。需要让连接定期轮换时，直接设置 db.SetConnMaxLifetime(d)：它限制连接可以被复用的最长时间，过期连接通常会在再次使用前被惰性关闭；d 表示不因连接年龄关闭。它解决的是“连接太老”，不是“空闲太久”或“并发太高”。

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

先用 SetConnMaxLifetime 控制连接年龄

最小配置只需要一行，但参数含义要先分清。下面的示例把“连接最多复用 30 分钟”写成连接池策略，同时把空闲时长和连接数量放在各自的配置项中：

package main

import (
    "database/sql"
    "time"
)

func configureDB(db *sql.DB) {
    // 连接达到年龄上限后，不再让它被新的操作长期复用。
    db.SetConnMaxLifetime(30 * time.Minute)
    // 这是空闲时间上限，与连接年龄是两个独立维度。
    db.SetConnMaxIdleTime(10 * time.Minute)
    // 下面两个参数只限制数量，不决定连接何时过期。
    db.SetMaxOpenConns(40)
    db.SetMaxIdleConns(20)
}

这里的 30 分钟不是通用答案。它表达的是策略：让长期运行的服务定期放弃旧连接，由连接池在后续请求中建立可用的新连接。没有明确的服务端或中间网络限制时，可以先保持默认的无限年龄，再根据连接错误和运维边界调整。

把生命周期、空闲时间和数量分开

连接池调参最容易出错的地方，是把三个维度混成一个“连接超时”。它们的行为不同：

因此，连接被服务端断开时，不要只把 SetMaxOpenConns 调小；并发上限变了，连接年龄并没有变。相反，若低峰期连接太多，优先看空闲时间和空闲数量，而不是盲目缩短最大生命周期。

按照服务端连接边界选择轮换参数

如果数据库、代理或网络设备对连接存活时间有明确限制，应用侧的最大生命周期应低于该限制，并为一次长查询、网络抖动和连接回收留出余量。例如上游大约允许 60 分钟，可以先把应用值放在 45～55 分钟，再结合连接错误和轮换计数观察，而不是直接卡在 60 分钟。

调整时记住两个事实：第一，过期连接可能在复用前才被关闭，设置生效不代表所有现存连接立刻同时断开；第二，生命周期过短会增加握手、认证和驱动初始化次数。连接轮换是降低长期复用风险的手段，不是替代连接池容量规划、事务超时或查询超时。

func applyLifetimePolicy(db *sql.DB, upstreamLimit time.Duration) {
    // 上游限制未知或无效时，保持默认策略，避免凭空制造轮换开销。
    if upstreamLimit  0 {
        db.SetConnMaxLifetime(lifetime)
    }
}

用 DBStats 检查连接轮换是否生效

配置后不要只看“接口还通不通”。DBStats 能提供连接池视角，其中 MaxLifetimeClosed 统计因 SetConnMaxLifetime 关闭的连接数量；OpenConnections、InUse 和 Idle 则帮助判断数量关系。

func reportPoolStats(db *sql.DB) {
    stats := db.Stats()
    // 轮换关闭数是累计值，适合用两次采样的差值判断近期变化。
    println("open", stats.OpenConnections)
    println("in_use", stats.InUse)
    println("idle", stats.Idle)
    println("lifetime_closed", stats.MaxLifetimeClosed)
}

采样时记录两个时间点的 MaxLifetimeClosed 差值，并同时看 InUse 是否长期接近上限。如果关闭数增长过快，可能是生命周期过短；如果一直为零，也只能说明采样窗口里没有发生按年龄关闭，不能据此证明设置没有加载。

生产配置的边界与复查清单

• 只想避免老连接长期复用时设置 SetConnMaxLifetime，不要用它解决单次 SQL 超时。
• 只想清理低峰期闲置连接时看 SetConnMaxIdleTime，不要把空闲和年龄混为一谈。
• 调整后检查 OpenConnections、InUse、Idle 和 MaxLifetimeClosed 的趋势。
• 确保每次 QueryContext、事务和 Conn 使用都有明确的关闭或提交路径，生命周期参数不能修复资源泄漏。

常见问题

SetConnMaxLifetime 会立即关闭所有超过时间的连接吗？

不要把它理解成定时器广播。官方文档描述的是过期连接可以在再次复用前惰性关闭；因此要结合后续请求和累计统计观察。

SetConnMaxLifetime 和 SetConnMaxIdleTime 能同时设置吗？

可以。一个约束连接年龄，一个约束连续空闲时长，实际关闭时取决于连接是否正在使用以及连接池何时复用它。

把生命周期设成 0 是不是关闭连接池？

不是。0 只表示不因连接年龄关闭；连接池仍会受最大打开数、最大空闲数、驱动和数据库服务端规则影响。