Go database/sql QueryContext 超时后如何判断连接是否可复用

我第一次处理 Go 的慢查询超时时，最容易犯的判断是：只要拿到了 context deadline exceeded，这条连接就一定坏了。其实两者不是一回事。QueryContext 的超时只说明这次操作没有在期限内完成；连接能否回到连接池，要继续看结果集是否关闭、驱动是否支持取消，以及驱动有没有明确返回 driver.ErrBadConn。

官方资料：https://pkg.go.dev/database/sql　取消说明：https://go.dev/doc/database/cancel-operations

先分清超时发生在查询还是读结果

我现在会先把错误位置分成两段：调用 db.QueryContext 时就返回错误，说明查询尚未交付出结果集；已经拿到 *sql.Rows，随后 Next 停止或 Err 返回错误，则说明问题出现在结果读取阶段。两种情况都可能和上下文超时有关，但不能因此推出“连接已损坏”。

queryCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel() // 释放超时上下文持有的计时器资源

rows, err := db.QueryContext(queryCtx, "SELECT id, name FROM users")
if err != nil {
	// 查询还没有交付 Rows，先按上下文或驱动错误分类。
	return fmt.Errorf("query users: %w", err)
}
defer rows.Close() // 无论后续 Scan 是否出错，都要释放结果集

for rows.Next() {
	var id int64
	var name string
	if err := rows.Scan(&id, &name); err != nil {
		// Scan 错误要保留原始错误，便于区分数据转换问题。
		return fmt.Errorf("scan user: %w", err)
	}
}
if err := rows.Err(); err != nil {
	// 迭代期间的网络、取消或驱动错误通常在这里暴露。
	return fmt.Errorf("iterate users: %w", err)
}
return nil

这里至少要记录 QueryContext 的返回错误、Rows.Err() 的返回错误和 Rows.Close() 的关闭错误。只记录一条“查询超时”日志，会把查询取消、网络断开和扫描失败混在一起，后面也就无法判断连接池是否出现异常。

看驱动是否真正实现取消

database/sql 的接口并不能替每个数据库驱动实现服务器端取消。驱动如果实现了 driver.QueryerContext，就应当遵守上下文取消契约；如果没有实现，database/sql 可能退回旧的 Queryer，甚至走 prepare/execute 路径。官方文档也明确提醒：不支持 context 取消的驱动，可能直到查询完成后才返回。

因此，超时后的第一问不是“要不要把连接杀掉”，而是“当前驱动收到取消了吗”。如果驱动只是在调用结束后检查上下文，应用层的超时日志与数据库服务器实际停止执行的时间可能不同；如果驱动能发送取消并正常清理结果集，连接仍可能继续被池管理。

图中的 driver.ErrBadConn 是另一个边界：它表示驱动已经判断连接处于不可用状态，database/sql 才会按坏连接路径处理。普通的 context.DeadlineExceeded 没有这个含义。不要在所有超时分支里手工关闭整个 *sql.DB，否则会把可复用的连接和连接池一起打断。

用 Close、ErrBadConn 和连接池指标做判断

对于已经拿到的 Rows，收尾顺序很重要：循环结束后显式调用 Close，再检查 Err；如果提前从循环返回，也要保证 Close 能执行。Rows.Close 负责释放结果集占用的资源，Rows.Err 负责报告迭代期间遇到的错误，它们分别回答“资源有没有收好”和“读取是否完整”。

DB.Stats 是连接池的聚合视图，适合看趋势，不能精确告诉你某一条查询使用了哪条物理连接。线上排查时，把查询名、超时原因、rows 关闭结果和池统计采样放在同一条请求日志里，比凭一个错误字符串猜测更可靠。

把超时处理写成可复用的收尾函数

我更倾向于让查询函数只返回分类后的原始错误，不在底层偷偷重试。读查询是否能重试，要看 SQL 是否幂等、超时发生在服务端执行前还是执行后，以及驱动是否已经判断连接状态。尤其是写入操作，网络断开后不能因为“没收到响应”就盲目重放。

func queryUsers(ctx context.Context, db *sql.DB) error {
	queryCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
	defer cancel() // 函数退出时停止计时器并传播取消

	rows, err := db.QueryContext(queryCtx, "SELECT id, name FROM users")
	if err != nil {
		if errors.Is(err, context.DeadlineExceeded) {
			// 只标记本次超时，不把连接直接判为坏连接。
			return fmt.Errorf("query timeout: %w", err)
		}
		return err
	}

	defer func() {
		// 即使调用方提前返回，也确保结果集回到 database/sql 的管理路径。
		_ = rows.Close()
	}()
	for rows.Next() {
		// 业务代码在这里完成 Scan；示例省略具体字段映射。
	}
	if err := rows.Err(); err != nil {
		return fmt.Errorf("rows incomplete: %w", err)
	}
	return nil
}

最终可以用四个问题复核：超时是在拿到 Rows 前还是之后？驱动是否实现了取消接口？Rows 是否明确关闭并检查了 Err？是否出现 ErrBadConn 或持续异常的 DB.Stats？只有这些证据拼起来，才足以决定连接是否需要被淘汰；单独看到 QueryContext 超时，不足以做这个决定。

相关问题

QueryContext 超时后还能继续使用同一个 *sql.DB 吗？

通常可以。*sql.DB 是连接池句柄，单次上下文超时不等于整个句柄失效；仍要看驱动返回和后续池指标。

为什么 rows.Close 不能省略？

完整读完时部分驱动会自动关闭，但提前返回、Scan 失败或取消时不能依赖这个细节。显式关闭能让资源收尾路径稳定。

发现 ErrBadConn 后要不要立即重试？

先确认操作是否幂等以及请求是否可能已经在数据库端生效。ErrBadConn 解决的是连接状态，不是业务重试授权。