Go database/sql 查询结果不用完为什么要关闭 Rows

如果 Go 代码通过 database/sql.Query 或 QueryContext 拿到 *sql.Rows，却只读取前几行就直接返回，问题不只是“少读了几条数据”。Rows 代表一次仍在进行中的结果集读取，及时调用 Close 才能结束这次读取并让底层连接回到可复用路径。正常遍历到结尾时驱动通常会自动完成一部分收尾，但业务代码仍应显式关闭，尤其是提前退出、扫描失败和多结果集场景。

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

实用规则是：Query 成功后立刻安排 defer rows.Close()；循环外检查 rows.Err()；如果特别关心多语句或驱动的关闭错误，再单独处理 Close 返回值。

为什么 Rows 不读完也要 Close

sql.DB 是连接池，不等于每次查询都会立即创建并独占一条永久连接。查询返回 Rows 后，驱动仍可能在读取结果、处理协议状态或等待后续结果。此时调用方持有的是“结果集读取句柄”，而不是一份已经与数据库脱钩的数据副本。提前返回时若不关闭，后续请求可能遇到连接池可用连接减少、查询排队变长等现象。

这也是为什么 defer rows.Close() 要放在错误判断之后、第一次使用 rows 之前：只有 QueryContext 成功拿到非空的 Rows，才需要安排关闭。

先固定一个可提前退出的安全模板

下面的函数只读取满足条件的前几行。无论循环因为数量够了、扫描失败还是上下文取消而离开，函数返回前都会执行关闭动作。

func loadNames(ctx context.Context, db *sql.DB, limit int) ([]string, error) {
	// 使用带上下文的查询，让请求取消能够传递到驱动。
	rows, err := db.QueryContext(ctx, `SELECT id, name FROM users ORDER BY id`)
	if err != nil {
		return nil, err
	}
	// Query 成功后立刻安排清理，覆盖提前 return 的分支。
	defer rows.Close()

	names := make([]string, 0, limit)
	for rows.Next() {
		var id int64
		var name string
		// Scan 错误属于当前行解析失败，先返回但仍让 defer 关闭 Rows。
		if err := rows.Scan(&id, &name); err != nil {
			return nil, err
		}
		names = append(names, name)
		if len(names) == limit {
			break // 只取前 limit 行时，不能假设剩余结果会自动释放。
		}
	}
	// Next 结束既可能是读完，也可能是驱动在迭代中遇到错误。
	if err := rows.Err(); err != nil {
		return nil, err
	}
	return names, nil
}

如果 limit 允许为零，生产代码可以在查询前直接返回，避免无意义地建立结果集。若业务只需要一条记录，则 QueryRowContext 加 Scan 通常更清楚，因为它不把多行结果集交给调用方管理。

Scan、Rows.Err 和 Close 的检查顺序

这三个位置的错误不能互相替代。Scan 关注当前行能否转换到目标变量；Rows.Err 关注 Next 迭代过程中的错误，例如驱动在继续取数据时报告了网络或协议问题；Close 负责结束结果集，某些驱动或多语句读取场景还可能在这里暴露收尾错误。

常见误区是把 for rows.Next() 结束理解为“必然正常”。它只表示没有下一行可供读取；是否因为读完、取消或驱动错误结束，要靠 Rows.Err 判断。另一个误区是把 defer 放在循环体内：大量循环会把清理推迟到外层函数结束，应该在创建结果集的函数边界内安排一次 defer。

用连接池指标和测试锁定释放边界

排查“数据库偶发卡住”时，可以先观察 db.Stats() 的 InUse、Idle、WaitCount 与 WaitDuration，再检查所有 Query 调用是否在成功后安排 Close。这些指标只能说明池的运行状态，不能替代对错误分支的代码检查。

测试时至少覆盖三条路径：查询失败、第一行扫描失败、读到一部分后提前返回。若函数设置了较小的 SetMaxOpenConns，连续执行这些用例更容易暴露未释放 Rows 的问题。上下文超时也应纳入测试，因为取消请求不等于调用方可以跳过清理。

如果查询的语义就是单行读取，使用 QueryRowContext 可以减少资源管理面；如果需要分页或流式读取，就保留 Rows，但让“获取成功即安排 Close、循环后检查 Err”成为固定代码形状。

相关问题

Rows 读到最后一行后还需要 Close 吗？

需要。读完可能触发部分自动收尾，但显式 Close 能让函数的资源责任清楚，也能覆盖未来改成提前返回的路径。

只查询一行还要用 Rows 吗？

通常不需要。优先使用 QueryRowContext，让单行语义和错误处理更直接；只有需要多结果集或统一遍历接口时才保留 Rows。

rows.Err 能代替 rows.Close 吗？

不能。Err 用于读取迭代错误，Close 用于结束结果集。两者解决的是不同阶段的问题。