Go database/sql 两个连接空闲时间参数有什么区别

在 Go 的 database/sql 连接池里，SetConnMaxIdleTime 和 SetConnMaxLifetime 都会让过期连接在再次复用前被关闭，但判断依据不同：前者看“连接连续闲置了多久”，后者看“连接从创建到现在活了多久”。一个连接可以一直被复用，却因为总年龄超过生命周期而被淘汰；也可以年龄不大，却因为长时间没有被使用而被淘汰。

官方地址：https://pkg.go.dev/database/sql#DB.SetConnMaxIdleTime

先用一条时间线分清两个参数

把一个连接画成从创建到关闭的一条时间线，区别就很直观。空闲时间只计算“连接归还连接池后没有被取走”的那一段；一旦连接再次被借出，这段连续空闲时间就被打断。生命周期则从连接创建开始持续累计，不会因为中间执行过查询而重新计时。

官方文档对两者的定义分别是“连接可以空闲的最长时间”和“连接可以被复用的最长时间”。当参数小于等于零时，对应规则不会因为空闲时长或连接年龄关闭连接。

最小配置应该这样写

两个参数都接收 time.Duration。生产配置通常把它们和最大打开数、最大空闲数放在一起，但它们解决的是不同问题：数量参数控制池的规模，时间参数控制连接的存活边界。

package main

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

func configurePool(db *sql.DB) {
	// 空闲连接连续 5 分钟没有被取用时，允许连接池在再次复用前淘汰它。
	db.SetConnMaxIdleTime(5 * time.Minute)

	// 连接从创建起超过 30 分钟后，即使期间被反复复用，也允许被替换。
	db.SetConnMaxLifetime(30 * time.Minute)

	// 数量限制与时间限制独立；这里避免流量突增时无限创建连接。
	db.SetMaxOpenConns(20)
	db.SetMaxIdleConns(5)
}

func openPool(driverName, dsn string) *sql.DB {
	// sql.Open 通常只创建连接池句柄，真正连接数据库由后续操作触发。
	db, err := sql.Open(driverName, dsn)
	if err != nil {
		log.Fatalf("open database: %v", err)
	}
	configurePool(db)
	return db
}

这段配置的含义不是“5 分钟一到就立刻关闭所有空闲连接”，也不是“30 分钟一到就中断正在执行的查询”。官方文档使用的是“可能在再次复用前惰性关闭”：连接池会在合适的检查点处理过期连接，应用不应把参数当成精确的定时器。

什么时候只设置空闲时间

如果主要问题是低峰期连接长期挂在池里，可以先设置 SetConnMaxIdleTime。例如定时任务白天有流量、夜间几乎没有访问，空闲连接不必一直保留到下一次高峰。

这条规则不限制活跃连接的总年龄。一个连接只要持续被使用，就不会因为“空闲时间”本身触发淘汰；因此它适合释放低峰期闲置资源，不适合处理连接长期复用后需要轮换的场景。

什么时候还要设置生命周期

如果驱动、代理、网络设备或数据库侧希望连接定期轮换，应该再设置 SetConnMaxLifetime。它关注的是连接年龄，而不是最后一次使用到现在的时间。高频请求会不断重置“空闲计时”，却不会重置“连接年龄计时”。

同时设置两个参数时，连接只要满足任意一条淘汰条件，就可能在下一次复用前被关闭并重新建立。可以按下面的判断选择：

用 DBStats 区分是哪条规则关闭了连接

DBStats 提供了 MaxIdleTimeClosed 和 MaxLifetimeClosed 两个累计计数，可以作为排查配置的观察点。它们只代表连接池因为对应规则关闭过多少连接，不代表数据库服务端主动断开了多少连接。

func logPoolStats(db *sql.DB) {
	stats := db.Stats()
	// 两个计数分别对应空闲时间规则和连接年龄规则的关闭次数。
	log.Printf(
		"open=%d idle=%d idle-time-closed=%d lifetime-closed=%d",
		stats.OpenConnections,
		stats.Idle,
		stats.MaxIdleTimeClosed,
		stats.MaxLifetimeClosed,
	)
}

如果只调整了空闲时间，却看到生命周期关闭计数持续增加，通常说明旧配置仍在生效、配置对象不是当前使用的 *sql.DB，或者代码把多个连接池的统计混在一起。反过来也一样：先确认读取的是同一个池，再根据计数变化判断规则。

三个容易混淆的边界

• 不是服务端超时。 数据库服务器、代理或网络设备的连接超时属于另一层；本篇两个方法只控制 database/sql 的连接池策略。
• 不是强制中断。 “超过生命周期”表示连接不应继续被复用，官方语义允许在再次复用前惰性关闭，不应把它理解为定时器到点杀掉正在执行的请求。
• 不是最大空闲数。 SetMaxIdleConns 控制最多保留多少个空闲连接，SetConnMaxIdleTime 控制某个连接连续空闲多久；一个按数量，一个按时间。

常见问题

连接每次查询后都重新建立，是不是生命周期参数太小？

不一定。还要看是否设置了很短的空闲时间、最大空闲数是否过小，以及驱动或服务端是否主动断开。先读取同一 *sql.DB 的 DBStats，再对照两个关闭计数。

把两个参数都设成 0 会怎样？

按官方定义，非正数不会因为对应的空闲时间或连接年龄关闭连接。它们不等于关闭连接池，也不改变最大打开数和最大空闲数的配置。

空闲时间应该比生命周期更长吗？

没有固定顺序。若目标是定期轮换，生命周期可以更短；若目标是尽快释放低峰连接，空闲时间可以更短。关键是先明确要限制“闲置多久”还是“总共活多久”。