本文深入解析 Go 程序中因连接重试机制导致的 PostgreSQL “Duplicate key violates unique constraint” 异常，揭示 database/sql 自动重试与 lib/pq 驱动行为之间的隐式风险，并提供基于事务、幂等设计和错误处理的生产级解决方案。
本文深入解析 go 程序中因连接重试机制导致的 postgresql “duplicate key violates unique constraint” 异常，揭示 `database/sql` 自动重试与 `lib/pq` 驱动行为之间的隐式风险，并提供基于事务、幂等设计和错误处理的生产级解决方案。
在高并发或网络不稳定的场景下，Go 应用向 PostgreSQL 插入数据时偶发出现 pq: duplicate key value violates unique constraint "bd_hash_index" 错误，是一个典型且易被误解的问题。表面上看，代码已通过内存哈希表（pr.BodiesHash）完成去重，逻辑看似严密；但问题根源并不在于业务逻辑，而在于 Go 标准库 database/sql 与 PostgreSQL 驱动 lib/pq 协同下的连接重试语义缺陷。
? 问题本质：自动重试破坏了操作的原子性与幂等性
database/sql 在执行 Exec() 时，若底层驱动返回 driver.ErrBadConn（例如 SSL 握手失败、连接中断、TLS renegotiation timeout），会默认最多重试 10 次（见源码中 maxBadConnRetries）。关键陷阱在于：该重试机制是无状态的——它无法判断前一次 INSERT 是否已被数据库成功执行。
假设以下时序发生：
- 应用发出 INSERT INTO bodies (...) VALUES ($1, ...)；
- 网络抖动导致 TCP 连接断开，lib/pq 收到 EOF 或 TLS error；
- 驱动错误地返回 ErrBadConn（违反官方文档“不应在可能已执行操作时返回该错误”的要求）；
- database/sql 自动在新连接上重放该 SQL；
- 第一次插入实际已成功提交（服务端无感知客户端断连），第二次重放触发唯一索引冲突。
这正是日志中偶发报错、且常伴随 SSL error 或 server closed the connection unexpectedly 的根本原因——它不是竞态条件（memory map 是 goroutine-local），而是 跨连接的非幂等重放。
✅ 正确解法：用事务 + 显式错误分类 + 幂等策略
1. 强制使用显式事务（推荐首选）
事务能确保语义完整性：连接中断 → 事务自动回滚 → 重试安全。更重要的是，sql.Tx 不参与 database/sql 的自动重试逻辑，所有错误将直接暴露给应用层，便于精确控制。
func (pr *Process) insertWithTx(bodyHash, bodyType, source, bodyStr string, ts int64) error {
tx, err := pr.DB.Begin()
if err != nil {
return fmt.Errorf("begin tx: %w", err)
}
defer tx.Rollback() // 注意：仅在未 Commit 时生效
stmt, err := tx.Prepare("INSERT INTO bodies (hash, type, source, body, created_timestamp) VALUES ($1, $2, $3, $4, $5)")
if err != nil {
return fmt.Errorf("prepare: %w", err)
}
defer stmt.Close()
_, err = stmt.Exec(bodyHash, bodyType, source, bodyStr, ts)
if err != nil {
var pgErr *pq.Error
if errors.As(err, &pgErr) && pgErr.Code == "23505" { // unique_violation
return nil // 忽略重复，视为成功（幂等）
}
return fmt.Errorf("exec: %w", err)
}
return tx.Commit() // 成功才提交
}? 提示：pq.Error.Code == "23505" 是 PostgreSQL 唯一约束冲突的标准 SQLSTATE 码，比字符串匹配更可靠。
2. 补充防御：UPSERT（ON CONFLICT DO NOTHING）
若业务允许忽略重复，直接使用 INSERT ... ON CONFLICT DO NOTHING 是最简洁的幂等方案，且由数据库保证原子性：
INSERT INTO bodies (hash, type, source, body, created_timestamp) VALUES ($1, $2, $3, $4, $5) ON CONFLICT ON CONSTRAINT bd_hash_index DO NOTHING;
对应 Go 调用无需事务，但需检查 sql.Result.RowsAffected() 是否为 0（表示被忽略）：
res, err := bodyInsert.Exec(bodyHash, p.GetType(), p.GetSource(), p.GetBodyString(), nowUnix)
if err != nil {
pr.Logger.Printf("insert failed: %v", err)
return
}
n, _ := res.RowsAffected()
if n == 0 {
pr.Logger.Printf("skipped duplicate hash: %s", bodyHash)
}3. 运维与配置优化
- 禁用非必要 SSL：若数据库部署于可信内网，连接字符串添加 sslmode=disable 可规避 TLS renegotiation 问题（Go 1.3–1.4 时期高频）；
- 升级驱动与 Go 版本：使用最新 github.com/lib/pq（或迁移到 github.com/jackc/pgx/v5）及 Go ≥1.18，显著改善 TLS 稳定性；
- 监控连接健康度：在 DB.SetMaxOpenConns() 和 DB.SetConnMaxLifetime() 基础上，添加连接池指标（如 sql.DB.Stats().OpenConnections）辅助诊断。
⚠️ 重要注意事项
- ❌ 切勿依赖内存 map 做全局去重：pr.BodiesHash 仅对单 goroutine 有效，若 Run() 被多处并发调用（如多个 Process 实例），该 map 完全失效；
- ❌ 避免在 Prepare 后 defer Close()：原代码中 defer bodyInsert.Close() 在循环外，会导致 prepare statement 提前关闭，应移至 Run() 函数末尾或改用 tx.Prepare()；
- ✅ 始终区分错误类型：对 pq.Error 进行 errors.As() 类型断言，针对性处理 23505（唯一冲突）、23503（外键）、08006（连接终止）等，而非统一 log.Println(err)；
- ✅ 启用 PostgreSQL 日志：设置 log_statement = 'ddl' 或 log_min_error_statement = error，结合 log_line_prefix = '%t [%p]: ' 定位冲突时刻的真实 SQL 与会话。
总结
“Duplicate key violates unique constraint” 在 Go + PostgreSQL 场景中，90% 以上并非数据逻辑错误，而是 连接层重试语义与数据库事务边界不一致引发的副作用。解决之道不在加锁或复杂同步，而在于：
- 用显式事务替代裸 Exec，切断自动重试链路；
- 用 ON CONFLICT 替代应用层判重，交由数据库保证幂等；
- 精准分类错误并主动重试，而非依赖不可控的底层重放。
最终，一个健壮的数据写入流程，应是「数据库负责一致性，应用负责可观测性与可恢复性」——这才是云原生时代数据操作的正确范式。
