Go sql.Rows 忘记 Close 为什么连接池逐渐耗尽

接口偶尔变慢，连接池的 InUse 一路升高，最后新的查询卡在等待连接。很多时候 SQL 本身并不慢，而是代码拿到 *sql.Rows 后，在扫描中途返回，却没有把 Rows 关闭。

只要调用了 Query、QueryContext 或事务上的查询方法，就应在确认没有错误后立刻注册 defer rows.Close()；循环结束后再检查 rows.Err()。Rows 没有关闭时，它占用的底层连接不能稳定回到连接池，达到 MaxOpenConns 后，后续请求就会排队。

这里的“逐渐耗尽”不是说数据库连接永远泄漏，而是应用在等待 Rows 被关闭的时间里不断积累占用。完整遍历通常会触发自动关闭，但提前返回、扫描失败、分页截断和上下文取消都不能靠这个行为兜底。

先分清 DB、Rows 和连接池的关系

*sql.DB 是并发安全的连接池句柄，不等于一条固定连接。一次 QueryContext 会借用连接并返回 Rows；Rows 还没结束时，这条查询的资源仍处在使用中。若处理函数在读完部分记录后直接 return，连接就可能长期留在 InUse，而不是回到 Idle。

可以先看四个统计量：InUse 表示正在使用的连接，Idle 表示空闲连接，WaitCount 表示等待连接的累计次数，WaitDuration 表示累计等待时长。它们适合看趋势，不应被误解为某一条 SQL 的耗时。

// 读取列表时把 Rows 的关闭责任绑定到当前函数的所有返回路径。
func listUsers(ctx context.Context, db *sql.DB) ([]User, error) {
	rows, err := db.QueryContext(ctx, `SELECT id, name FROM users WHERE enabled = ?`, true)
	if err != nil {
		return nil, err
	}
	// 即使 Scan 失败、ctx 超时或业务提前返回，也要释放查询资源。
	defer rows.Close()

	users := make([]User, 0)
	for rows.Next() {
		var u User
		if err := rows.Scan(&u.ID, &u.Name); err != nil {
			return nil, err
		}
		users = append(users, u)
	}
	// Next 返回 false 可能是遍历结束，也可能是驱动或上下文错误。
	if err := rows.Err(); err != nil {
		return nil, err
	}
	return users, nil
}

关键位置不是把 Close 写在循环之后，而是拿到 Rows 并确认 err == nil 后立即注册。这样函数中任何一条后续返回路径都会执行清理。

为什么只写 for rows.Next 还不够

Next 返回 false 有两种含义：没有下一行，或者迭代过程中发生了错误。官方 API 要求用 rows.Err() 区分它们。因此，下面两种写法都不完整：只在循环内 Scan、不检查 Err；或者在 Scan 失败时返回，却没有提前注册 Close。

正常只读查询里，显式 Close 的错误通常可以和主错误一起记录；但多语句结果、写入型语句或驱动明确返回关闭错误时，不应默默丢弃。需要把“读取失败”“关闭失败”“迭代失败”分开处理，避免最后只看到一个模糊的数据库错误。

用 Stats 判断连接是否真的回来了

修复后不要只看接口成功率。可以在诊断日志或指标采样里记录：

• InUse 长期贴近 MaxOpenConnections，同时请求等待变多，优先排查 Rows、事务和 Conn 是否未收尾。
• WaitCount 持续增长但 SQL 延迟没有同步增长，说明瓶颈可能在池内资源归还，而不是数据库执行计划。
• Idle 始终为零不一定是泄漏，也可能是并发确实超过池容量；要和 WaitDuration、请求量及查询耗时一起看。

// 只记录连接池快照，不把累计计数误当成当前等待人数。
func logDBStats(db *sql.DB, logf func(string, ...any)) {
	s := db.Stats()
	logf("db pool: in_use=%d idle=%d wait_count=%d wait_duration=%s max_open=%d",
		s.InUse, s.Idle, s.WaitCount, s.WaitDuration, s.MaxOpenConnections)
}

事务、分页和超时的三个边界

事务内查询要让 Rows 和事务都在明确的生命周期中结束：Rows 先收尾，再提交或回滚；不要把 Rows 带出事务函数。分页只取一页时尤其容易提前返回，仍然需要 Close。使用 QueryContext 时，超时可能让 Next 停止并在 Err 中暴露上下文错误，不能把“没有更多行”当成成功。

最后检查代码审查清单：每个返回 Rows 的调用点后是否紧跟 Close；每个 for rows.Next() 后是否检查 Err；Scan 失败是否能触发清理；连接池是否设置了合理的上限和观测指标。这样修复的是资源生命周期，而不是靠盲目调大连接数掩盖问题。

相关问题

QueryRow 也需要手动 Close 吗？通常不需要直接关闭 Rows；QueryRow 返回的是延迟执行的 *sql.Row，重点是检查 Scan 返回的错误。

完整遍历后还要 Close 吗？完整遍历结束时 Rows 会自动关闭，但保留显式 Close 能统一表达责任，也能覆盖未来改成提前返回的路径。

把 MaxOpenConns 调大能解决吗？只能延后等待出现的时间。若 Rows、事务或连接没有及时归还，池上限越大，数据库端和应用端积累的占用也可能越多。