sqlRows没有关闭导致连接池堵塞怎么办

如果 Go 服务里使用 db.Query 或 db.QueryContext 后没有及时关闭 sql.Rows，最容易看到的现象就是请求越来越多时连接池等待上升，后续查询像“堵在数据库前面”。修复的第一步不是盲目把连接池调大，而是让每个结果集都有明确的关闭边界。

最小修复通常是：查询成功后立刻执行 defer rows.Close()，循环结束后检查 rows.Err()。如果函数会提前返回，这个模板能把 Scan 失败、业务过滤和参数错误等路径一起覆盖。

官方文档：https://go.dev/doc/database/querying

先把 Rows 的资源边界固定下来

sql.Rows 不是普通的内存切片，它代表一个正在读取的结果集。驱动可能仍持有底层连接，直到结果读完或结果集被关闭。查询成功后马上注册关闭动作，可以把资源释放和函数生命周期绑定：

func listUsers(ctx context.Context, db *sql.DB) ([]User, error) {
    // 查询上下文让调用方可以取消长时间等待的数据库操作。
    rows, err := db.QueryContext(ctx, `SELECT id, name FROM users ORDER BY id`)
    if err != nil {
        return nil, err
    }
    // 无论后续是 Scan 失败、业务提前返回还是正常结束，都释放结果集。
    defer rows.Close()

    users := make([]User, 0, 32)
    for rows.Next() {
        var user User
        // Scan 负责把当前行的列复制到目标字段。
        if err := rows.Scan(&user.ID, &user.Name); err != nil {
            return nil, err
        }
        users = append(users, user)
    }
    // Next 返回 false 可能是读完，也可能是驱动或网络错误。
    if err := rows.Err(); err != nil {
        return nil, err
    }
    return users, nil
}

这里的关键不是 defer 本身有多神奇，而是它在拿到 rows 后立刻建立了“谁创建、谁负责收尾”的关系。Close 可以重复调用，因此即使完整遍历后由标准库自动关闭，显式关闭也不会破坏结果。

为什么循环读完了还建议 Close

标准库文档说明，当 Rows.Next 返回 false 且没有更多结果集时，结果集会自动关闭，所以只写“完整循环一定泄漏”并不准确。真正危险的是函数在循环中途离开：例如某一行 Scan 出错、业务发现重复数据直接返回，或者只取前几行就把函数交给上层。

因此应把两件事分开看：

• defer rows.Close() 负责兜底释放，覆盖提前返回。
• rows.Err() 负责告诉你遍历是否因为驱动、网络或上下文错误而中断。

如果只写 for rows.Next() 而忽略 Err，服务可能把一个不完整结果当成成功；如果只在循环自然结束后手动关闭，又可能漏掉循环体内的返回路径。

长查询要把取消信号传到底层

没有关闭结果集和查询本身迟迟不结束，是两个相邻但不同的问题。对于可能等待锁、扫描大量数据或依赖网络的查询，使用带超时的上下文，让驱动在超时后有机会停止工作并释放相关资源：

func loadRecent(ctx context.Context, db *sql.DB) ([]Order, error) {
    // 超时只约束本次查询，避免请求取消后仍无限等待。
    queryCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()

    rows, err := db.QueryContext(queryCtx, `
        SELECT id, user_id, total
        FROM orders
        WHERE created_at > ?
        ORDER BY created_at DESC`, time.Now().Add(-time.Hour))
    if err != nil {
        return nil, err
    }
    // 只要函数离开，就主动结束结果集的使用。
    defer rows.Close()

    orders := make([]Order, 0, 64)
    for rows.Next() {
        var order Order
        // 这里的 Scan 错误不能被吞掉，否则返回的数据可能不完整。
        if err := rows.Scan(&order.ID, &order.UserID, &order.Total); err != nil {
            return nil, err
        }
        orders = append(orders, order)
    }
    // 统一检查取消、驱动和网络层传回的迭代错误。
    if err := rows.Err(); err != nil {
        return nil, err
    }
    return orders, nil
}

上下文取消不能替代 Close：它负责通知查询停止，Close 负责结束结果集的使用边界。两者一起写，才能覆盖“查询还没返回”和“查询已经返回但读取中途退出”这两类情况。

用 DBStats 判断到底是不是连接池堵塞

sql.DB 自身维护连接池。看到接口变慢时，先观察 InUse、Idle、WaitCount 和 WaitDuration，再决定是修复资源释放，还是调整容量：

func reportPool(db *sql.DB) string {
    // Stats 是一个快照，用于把“感觉堵塞”变成可比较的指标。
    stats := db.Stats()
    return fmt.Sprintf(
        "open=%d in_use=%d idle=%d waits=%d wait_duration=%s",
        stats.OpenConnections,
        stats.InUse,
        stats.Idle,
        stats.WaitCount,
        stats.WaitDuration,
    )
}

如果 InUse 长时间接近 MaxOpenConnections，同时 WaitCount 和 WaitDuration 持续增加，说明调用方在等待可用连接。但这仍要结合代码和查询时长判断：

• 部分请求提前返回且 InUse 不回落，优先查 Rows.Close、事务提交/回滚和专用连接关闭。
• InUse 稳定回落但等待很多，可能是并发高于池容量或查询本身太慢。
• Idle 很低不一定是故障，连接池可能正在按需创建连接；要看一段时间内的趋势。

调大 SetMaxOpenConns 只能改变并发上限，不能修复没有关闭结果集的调用路径；上限过大还可能把压力直接推给数据库。

把修复收敛成一份查询清单

我在排查这类问题时，会把每个多行查询都按下面的顺序过一遍：

1. 查询成功后是否立刻 defer rows.Close()？
2. 循环内是否存在错误返回、分页截断或把 rows 交给异步任务的路径？
3. 循环结束后是否检查 rows.Err()？
4. 外部请求取消时，是否使用了 QueryContext 而不是无上下文的 Query？
5. 是否记录了 DBStats，能够区分资源未释放与池容量不足？

如果这五项都满足，连接池仍然等待，就继续查慢查询、锁等待、事务边界和数据库服务端连接限制，而不要继续把问题简单归因于 sql.Rows。

几个容易混淆的问题

只查询一行也需要 Close 吗？

如果使用 QueryRowContext，通常通过 Scan 完成单行读取，不需要像多行 Rows 那样手动管理结果集；不要为了单行查询强行套用多行循环模板。

Close 返回错误要不要检查？

在大多数读取场景，先保证关闭动作一定执行更重要；如果驱动把关闭阶段的错误作为业务一致性信号，就在明确的资源收尾位置记录或返回它。不要因为处理 Close 错误而删除前面的 rows.Err() 检查。

连接池堵塞时先调哪个参数？

先确认结果集、事务和专用连接都能释放，再用 DBStats 观察等待趋势，最后根据数据库承载能力调整 MaxOpenConns 和 MaxIdleConns。参数调整是容量决策，不是泄漏修复。

记住一句话：多行查询的安全模板是“查询成功立刻 Close 兜底，循环结束检查 Err，长查询绑定 Context，池堵塞用 Stats 证明”。这样处理后，才能知道真正需要修的是代码生命周期、查询耗时，还是连接池容量。