Go database/sql driver.ErrBadConn 什么时候可以让连接池重试

如果 Go 的数据库驱动确认当前连接已经失效，而且这次操作还没有可能在服务端生效，就可以返回 driver.ErrBadConn。database/sql 会用 errors.Is 识别它，并尝试换连接；但如果请求已经发出、服务端可能执行过写操作，就不能为了“让它重试”而把普通错误改成 ErrBadConn，否则可能造成重复执行。

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

这条规则的重点不是“遇到错误就重试”，而是把“连接坏了”和“操作结果不确定”分开。前者由驱动交给连接池处理，后者必须交给业务决定。

先判断：坏的是连接，还是操作结果

ErrBadConn 描述的是 driver.Conn 已经处于坏状态，例如服务端提前关闭了连接。它不是业务错误码，也不是建议调用方无限重试的信号。

我在排查这类问题时会先问一个问题：当前 SQL 有没有可能已经到达服务端？如果连接在写入前就确认失效，驱动可以返回 ErrBadConn；如果请求已经发出，随后只收到网络断开或协议错误，就不能确定服务端是否已经执行。

// 下面是驱动内部错误分类的示意，重点是区分“未发送”和“结果未知”。
func classifyWriteError(requestSent bool, err error) error {
	// 请求还没有交给服务端，连接已确认失效，可以安全交给连接池换连接。
	if !requestSent && errors.Is(err, net.ErrClosed) {
		return driver.ErrBadConn
	}

	// 请求已经发送，服务端可能完成了写操作，必须保留原始错误。
	return err
}

示意代码表达的是判断原则。真实驱动应根据自己的协议状态、写入阶段和服务端响应语义做判断，不能仅凭“网络报错”四个字就返回 ErrBadConn。

database/sql 怎样识别并重试 ErrBadConn

调用方通常使用的是 *sql.DB，并不直接管理每一条 driver.Conn。在数据库驱动返回 ErrBadConn 后，database/sql 会通过 errors.Is 判断错误是否包含它，并把坏连接从可复用连接池中移除。

Go 标准库的重试入口会先尝试可复用或新建的连接；连续遇到坏连接后，再使用“必须新建连接”的策略进行最后一次尝试。源码中的 maxBadConnRetries 为 2，因此不要把它理解为无限重试，更不要在业务层再次无条件套循环。

驱动实现中，哪些位置适合返回它

标准库文档明确给出了几个典型位置：查询或执行方法已经确认连接处于无效状态时，或者 SessionResetter.ResetSession 发现会话不能继续复用时。Pinger.Ping 返回它时，database/sql 会把该连接从池中移除。

// 驱动的会话重置示意：重置失败且连接不可再用时，通知 database/sql 丢弃它。
func (c *Conn) ResetSession(ctx context.Context) error {
	// 先检查上下文，避免在调用方已经取消后继续占用连接。
	if err := ctx.Err(); err != nil {
		return err
	}

	// 会话状态已无法恢复，返回 ErrBadConn 让连接池移除当前连接。
	if c.sessionIsBroken() {
		return driver.ErrBadConn
	}
	return nil
}

这里有一个容易忽略的区别：Validator.IsValid 返回 false 可以让连接不再放回空闲池，但它不是把一条已经发出的 SQL 变成可安全重试的授权。驱动仍然需要保留真实的执行错误。

业务代码不要手动伪造 ErrBadConn

使用 database/sql 的业务代码应该让 *sql.DB 管理连接，自己只处理最终返回的错误。不要在 ExecContext 返回普通错误后统一改写成 driver.ErrBadConn，也不要因为一次超时就再包一层无限重试。

func saveOrder(ctx context.Context, db *sql.DB, orderID int64) error {
	// 让 database/sql 自己处理驱动声明的坏连接，不在这里伪造 ErrBadConn。
	_, err := db.ExecContext(ctx,
		"UPDATE orders SET state = ? WHERE id = ?",
		"paid", orderID,
	)
	if err != nil {
		// 保留原始错误链，便于上层用 errors.Is 或 errors.As 判断原因。
		return fmt.Errorf("save order %d: %w", orderID, err)
	}
	return nil
}

如果这是幂等查询，业务层可以根据自己的错误模型设计有限重试；如果这是扣库存、扣款或写入状态的操作，网络断开后的结果可能未知，更应该先查询业务状态或使用幂等键，而不是强行套用 ErrBadConn。

遇到错误时可以这样快速判断

• 连接在请求发送前已确认关闭：由驱动返回 ErrBadConn。
• ResetSession 无法恢复会话：返回 ErrBadConn，让连接退出池。
• 服务端已经收到写请求，但客户端没有拿到结果：保留原始错误，不返回 ErrBadConn。
• 普通 SQL 语法、约束或业务错误：保留驱动错误，由业务处理。
• 请求被 context 取消：返回上下文错误，不把取消伪装成坏连接。

一句话总结：driver.ErrBadConn 是驱动和 database/sql 之间的连接生命周期契约，不是业务层的通用重试按钮。只有在“连接确实坏了，而且本次操作不可能已经生效”时，连接池重试才是安全的。

相关问题

驱动可以把 ErrBadConn 包装后再返回吗？

可以，只要错误链能被 errors.Is(err, driver.ErrBadConn) 识别；但包装前提仍然是连接坏了且不会造成重复操作。

业务层应该捕获 driver.ErrBadConn 吗？

通常不需要把它当作业务重试信号。database/sql 会先处理连接替换，业务层拿到的是最终结果；只有在实现驱动或排查连接生命周期时，才需要直接关注这个错误。