Go database/sql Rows 未关闭造成连接耗尽的诊断

这类故障最容易误判的地方，是接口开始超时后，大家第一反应往往是“数据库慢了”。我遇到过的典型现场却是：单独执行 SQL 很快，数据库 CPU 也不高，但 Go 服务里的请求越来越多地卡在获取连接。最后沿着 database/sql 的资源生命周期检查，才发现某个提前返回分支拿到了 *sql.Rows，却没有关闭它。

直接结论：如果 DB.Stats() 中 InUse 长时间贴近 MaxOpenConnections，Idle 很低，同时 WaitCount 和 WaitDuration 持续增长，就应该检查所有 Query/QueryContext 返回的 Rows 是否在每条退出路径上被关闭。查询成功后立即 defer rows.Close()，遍历结束再检查 rows.Err()，通常是最稳妥的收口方式。

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

影响面：SQL 不慢，连接池却开始排队

sql.DB 不是一条固定连接，而是一个并发安全的数据库句柄，内部管理连接池。一次返回多行结果的查询会得到 *sql.Rows。在 Rows 仍然持有底层资源时，相应连接不能像空闲连接那样被其他请求自由复用。

这会形成一种很有迷惑性的影响面：低并发时几乎看不出问题；并发一上来，未关闭的 Rows 累积，连接池里的可用连接越来越少，后续请求开始等待。此时应用侧看到的是延迟上升和超时，数据库侧却未必出现一条特别慢的 SQL。

官方文档说明，Rows.Close 会停止继续枚举结果；当 Rows.Next 到达末尾且没有更多结果集时，Rows 会自动关闭。但“读到末尾会自动关闭”并不等于任何分支都可以不写 Close。业务代码经常会提前返回、提前 break，或者 Scan 失败后直接退出，这些路径都不能依赖遍历自然结束。

时间线：为什么问题通常是逐渐出现的

我更愿意把这类故障按资源变化来看，而不是只盯着一条报错。一个常见时间线是：

• 请求量较低时，连接池仍有空闲连接，漏关 Rows 没有立即表现为错误；
• 出现特定数据或分支后，函数提前 return，Rows 生命周期跨过了业务需要的范围；
• InUse 上升、Idle 下降，但接口还能靠剩余连接工作；
• 达到 MaxOpenConns 后，新查询开始等待，WaitCount 与 WaitDuration 累积；
• 上游 Context 到期，日志里才出现查询超时、请求取消或 deadline exceeded。

这里没有必要虚构一个固定阈值。连接池大小、并发模式、SQL 返回量和驱动行为都不同，真正有价值的是看组合趋势：池是否长期满载、等待是否单调增加、空闲连接是否长期接近零，以及这些变化是否与某个接口调用量同步。

第一条证据：用 DB.Stats 看连接池压力

DB.Stats() 返回当前池状态和累计计数。排查时我会定期采集它，而不是只在故障发生后临时打印一次。下面的示例把关键字段输出为结构化日志；实际项目可以接入已有指标系统。

func logDBStats(ctx context.Context, db *sql.DB, logger *slog.Logger) {
    ticker := time.NewTicker(10 * time.Second)
    defer ticker.Stop() // 函数退出时释放定时器资源

    for {
        select {
        case 

这些字段应该成组解释：

需要强调的是，这些指标只能证明“连接池有压力”，不能单独证明一定是 Rows 未关闭。长事务、慢查询、显式占用 sql.Conn、数据库网络阻塞等也可能制造相似现象。下一步必须回到代码所有权。

触发条件：提前 return、break 和嵌套查询

最容易漏掉的代码通常不是正常循环，而是异常分支。下面这段代码在找到目标后直接返回，但没有关闭 rows。如果结果集没有自然遍历到末尾，资源释放就不再由“Next 返回 false”兜底。

func findEnabledProduct(ctx context.Context, db *sql.DB) (*Product, error) {
    rows, err := db.QueryContext(ctx,
        "SELECT id, name, enabled FROM products WHERE enabled = ?", true)
    if err != nil {
        return nil, fmt.Errorf("query products: %w", err)
    }
    // 问题点：没有在查询成功后立即安排 rows.Close()

    for rows.Next() {
        var p Product
        if err := rows.Scan(&p.ID, &p.Name, &p.Enabled); err != nil {
            return nil, fmt.Errorf("scan product: %w", err) // 提前返回会跳出遍历
        }
        if p.Enabled {
            return &p, nil // 未读完结果集，也没有显式关闭 Rows
        }
    }
    return nil, rows.Err()
}

另一种放大器是“外层 Rows 还没结束，循环体里又发起查询”。如果 MaxOpenConns 很小，外层查询占住一条连接，内层查询继续申请连接；多个并发请求同时进入后，很快就可能互相等待。嵌套查询不一定错误，但必须明确每个 Rows 的生命周期，必要时先把外层数据读入内存并关闭，再做下一轮查询。

根因：Rows 的所有权没有落到具体函数

真正的根因通常不是“忘了一行 defer”这么简单，而是代码没有明确谁负责关闭 Rows。只要函数返回 *sql.Rows 给上层，关闭责任就发生转移；一旦调用者里存在多个 return 分支，责任很容易丢失。

我在代码审查里会问三个问题：

1. 哪个函数调用了 Query 或 QueryContext？
2. 哪个函数拥有返回的 Rows，并保证所有退出路径都调用 Close？
3. 遍历结束后，谁检查 rows.Err()，避免把迭代错误当成正常结束？

如果这三个问题无法在一个很小的代码范围里回答，资源所有权就过于分散。相比把 Rows 层层向上传，我更倾向于在数据访问函数内部完成遍历，返回普通结构体切片或领域对象。

修复动作：把关闭责任固定在 Query 成功之后

最小修复模式很直接：Query 返回错误检查通过后，立即 defer rows.Close()；循环内部只负责 Scan 和业务判断；循环结束后检查 rows.Err()。即使后面新增提前返回分支，defer 也会守住资源边界。

func queryProducts(ctx context.Context, db *sql.DB) ([]Product, error) {
    queryCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel() // 释放派生 Context 持有的资源

    rows, err := db.QueryContext(queryCtx,
        "SELECT id, name, enabled FROM products WHERE enabled = ?", true)
    if err != nil {
        return nil, fmt.Errorf("query products: %w", err)
    }
    defer rows.Close() // Query 成功后立即固定关闭责任

    products := make([]Product, 0, 16)
    for rows.Next() {
        var p Product
        if err := rows.Scan(&p.ID, &p.Name, &p.Enabled); err != nil {
            return nil, fmt.Errorf("scan product: %w", err)
        }
        products = append(products, p)
    }

    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("iterate products: %w", err) // 区分正常结束与迭代失败
    }
    return products, nil
}

Context 超时很重要，但它不是 Close 的替代品。官方文档建议使用 QueryContext 传播取消，并对 context.WithTimeout 返回的 cancel 函数执行 defer。这样客户端断开或超时后，数据库操作有机会停止；Rows 的关闭责任仍然应该清晰存在。

如果只需要一行数据，直接用 QueryRowContext 往往更合适，既表达“最多一行”的意图，也避免调用者维护多行游标：

func productName(ctx context.Context, db *sql.DB, id int64) (string, error) {
    var name string
    err := db.QueryRowContext(ctx,
        "SELECT name FROM products WHERE id = ?", id,
    ).Scan(&name) // QueryRowContext 将单行读取与 Scan 合并在调用点
    if err != nil {
        return "", fmt.Errorf("query product name: %w", err)
    }
    return name, nil
}

修复后怎么复查

我不会只看“代码已经加了 defer”就宣布结束，而会复查同一业务流量下的资源趋势：

• InUse 是否能在请求高峰后回落；
• Idle 是否重新出现，而不是长期为零；
• WaitCount 和 WaitDuration 的增量是否显著下降；
• 请求超时是否与连接等待同步减少；
• 所有 Query 调用是否都能找到紧邻的 Close 责任。

测试时可以把连接池上限临时设得较小，让资源泄漏更容易暴露，但不要把测试配置直接照搬到生产。更重要的是覆盖提前 return、Scan 失败、Context 取消和只读取第一条记录等分支。

func configureDB(db *sql.DB) {
    db.SetMaxOpenConns(8) // 示例上限仅用于测试环境放大连接等待现象
    db.SetMaxIdleConns(8) // 让空闲容量不超过开放连接上限
    db.SetConnMaxIdleTime(5 * time.Minute) // 回收长期空闲连接，不替代 Rows.Close
}

防复发：把资源约束写进团队习惯

对我来说，最有效的防复发措施不是记住某次事故，而是减少“需要记住”的地方：

• Query 成功后的下一段代码就写 defer rows.Close()，不把它放到几十行之后；
• 只取一行时使用 QueryRowContext，不为单行结果创建多行遍历；
• 数据访问层尽量返回领域对象，不把 *sql.Rows 跨层传递；
• 为 InUse 接近上限、等待计数增量和等待时长增量建立监控；
• 为提前返回、取消和扫描错误编写测试，让非正常路径也执行资源收口。

相关问题

Rows 遍历完了还必须调用 Close 吗？

当 Next 返回 false 且没有更多结果集时，Rows 会自动关闭。但显式 defer rows.Close() 能覆盖提前 return、break 和 Scan 失败等分支，代码意图也更清楚。

只看 InUse 很高能确认是 Rows 泄漏吗？

不能。InUse 高只说明连接正在被占用。还要结合 Idle、WaitCount、WaitDuration、慢查询、事务、显式 Conn 使用和代码调用链一起判断。

增加 MaxOpenConns 能解决问题吗？

它可能暂时延后耗尽，但不能修复未关闭 Rows。盲目增大还会把压力传给数据库。应先修复资源生命周期，再根据数据库容量与负载调整池参数。

Context 超时后还要 Close Rows 吗？

要。Context 用于取消操作和限制等待时间，Close 用于明确结束 Rows 枚举并释放相关资源，两者职责不同。

这类故障的判断核心可以压缩成一句话：先用池指标确认“连接正在等待”，再用 Rows 所有权确认“谁没有收口”。当关闭责任、迭代错误和取消边界都落在一个函数里，连接耗尽就不再是一场只能靠猜的事故。