Go database/sql Rows确保 Rows 关闭并释放连接的处理方案

在 Go 的 database/sql 中，查询多行数据后最稳妥的收尾方式是：成功拿到 *sql.Rows 后立刻注册 defer rows.Close()，循环使用 Next 和 Scan，循环结束再检查 rows.Err()；对特别关注资源回收的服务，还应显式处理 Close 返回的错误。这样既覆盖正常读完，也能覆盖扫描失败、提前返回和请求取消，避免结果集长期占着连接。

一句话记忆：Rows 的责任不是“循环结束就自然消失”，而是“拿到后立刻安排 Close，读完后再检查 Close 和 Err”。

本文范围：只讨论 Go database/sql 的 Rows 读取与连接释放，不涉及 ORM 选型。示例中的驱动名和 DSN 由项目自行替换。

Rows 为什么会影响连接释放

*sql.DB 是连接池入口，QueryContext 返回的 *sql.Rows 代表仍在消费的结果集。只要 Rows 没有读完或关闭，驱动可能仍需要保留这次查询对应的连接。对于 HTTP 接口，最容易漏掉 Close 的位置是循环中途的 return、Scan 失败分支和业务过滤后的提前结束。

一套可复用的 Rows 收尾写法

把关闭责任放在拿到 Rows 的同一层，后续每个分支都能得到兜底。下面的写法还保留了关闭错误和迭代错误的区分：

func listUsers(ctx context.Context, db *sql.DB) ([]User, error) {
    // 给一次查询设置上限，客户端取消时也能把取消信号传给驱动。
    queryCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel()

    rows, err := db.QueryContext(queryCtx, `
        SELECT id, name, state
        FROM users
        WHERE state = ?
        ORDER BY id`, "active")
    if err != nil {
        return nil, fmt.Errorf("query users: %w", err)
    }
    // 无论后面是正常结束还是提前返回，都先保证结果集有关闭路径。
    defer rows.Close()

    users := make([]User, 0, 16)
    for rows.Next() {
        var user User
        // Scan 失败时立即退出，defer 会负责关闭 Rows。
        if err := rows.Scan(&user.ID, &user.Name, &user.State); err != nil {
            return nil, fmt.Errorf("scan user: %w", err)
        }
        users = append(users, user)
    }

    // Next 结束不等于查询全过程无错，还要读取迭代错误。
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("iterate users: %w", err)
    }
    return users, nil
}

这里的关键顺序是“QueryContext 成功后马上 defer Close”，而不是等所有业务逻辑完成后再想起资源释放。Next 返回 false 可能表示正常结束，也可能表示驱动或上下文错误，所以 Err 不应省略。

正常结束和异常返回都要收尾

defer rows.Close() 适合做可靠兜底，但如果业务需要把关闭阶段的错误返回给调用方，可以把关闭动作集中到一个具名返回值函数中：

func collect(ctx context.Context, db *sql.DB) (items []Item, err error) {
    // 查询失败没有 Rows，因此只在成功后建立关闭责任。
    rows, err := db.QueryContext(ctx, "SELECT id, value FROM items")
    if err != nil {
        return nil, err
    }
    // 先用 defer 兜底；若 Close 真正返回错误，则保留它。
    defer func() {
        if closeErr := rows.Close(); err == nil && closeErr != nil {
            err = fmt.Errorf("close rows: %w", closeErr)
        }
    }()

    for rows.Next() {
        var item Item
        if scanErr := rows.Scan(&item.ID, &item.Value); scanErr != nil {
            return nil, scanErr
        }
        items = append(items, item)
    }
    if err := rows.Err(); err != nil {
        return nil, err
    }
    return items, nil
}

不需要把所有错误都改写成“连接泄漏”。Scan 错误、Rows.Err 和 Close 错误分别发生在不同阶段；日志中保留阶段名，排查时才知道是数据映射、迭代，还是结果集关闭出了问题。

连接池排查要看什么

当服务表现为连接数持续升高、请求等待数据库或偶发超时，先确认 Rows 的每条路径都能到达 Close，再观察连接池统计。下面的采样代码只展示指标含义，不依赖具体驱动：

func logPoolStats(db *sql.DB, logger *log.Logger) {
    stats := db.Stats()
    // InUse 长期偏高表示连接被业务占用，WaitCount 可提示池外等待。
    logger.Printf("db pool open=%d in_use=%d idle=%d wait=%d",
        stats.OpenConnections, stats.InUse, stats.Idle, stats.WaitCount)
}

InUse 长时间接近 MaxOpenConnections，同时 WaitCount 增长，值得优先检查长时间未结束的 Rows、事务内读取和查询超时。SetMaxOpenConns 只能限制上限，不能替代 Rows 的生命周期管理。

常见误区与小结

• 只写 for rows.Next() 而不检查 rows.Err()，会漏掉迭代或上下文取消错误。
• 把 defer rows.Close() 放到很深的循环里，批量处理时可能让多个结果集同时存活；应缩小函数边界或显式关闭。
• 提前返回不是不关闭的理由；成功拿到 Rows 的下一行就应注册兜底。

最终可以把规则压缩为三点：查询成功立即安排 Close；每次 Scan 失败立即返回；循环结束同时看 Close 和 Err。再结合 QueryContext 和连接池统计，Rows 占用连接的问题就有了清晰的处理边界。

相关问答

Rows.Next 返回 false 就一定是正常结束吗？
不一定。它也可能意味着驱动、网络或上下文出现问题，因此循环后必须调用 rows.Err()。

已经读完所有行，还需要 Close 吗？
建议保留显式关闭或 defer 兜底。它让提前返回、扫描失败和未来修改后的异常路径拥有一致的资源释放策略。