数据库操作卡死主因是首次db.Query/Exec未用context.WithTimeout，sql.Open仅初始化不建连，真正连接在首次查询时发起且无超时会卡数分钟；正确做法是每次DB操作显式传带超时的context。
数据库操作卡死，不是 sql.Open 没设对，而是第一次 db.Query 或 db.Exec 时没加 context.WithTimeout —— 这才是绝大多数人踩坑的起点。
为什么 sql.Open 不会触发连接超时
sql.Open 只是初始化一个 *sql.DB 对象，不建连、不验证、不拨号。真正发起 TCP 连接是在第一次调用 db.Query、db.QueryRow 或 db.Exec 的瞬间。如果你没给这次调用传带超时的 context，它就会卡在 net.Dial 阶段，直到系统默认的 TCP connect timeout（通常是几分钟），期间 goroutine 挂起、HTTP handler 阻塞、连接池被占满。
常见错误现象：
- 服务启动正常，但首次查询 DB 就 hang 住几十秒甚至更久
- DB 宕机或防火墙拦截后，所有请求持续等待，无报错也无响应
- 压测时 QPS 上不去，
pprof显示大量 goroutine 停在net.(*pollDesc).wait
正确做法是：每次执行前都显式传入 context，例如：
立即学习“go语言免费学习笔记（深入）”；
ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second) defer cancel() rows, err := db.QueryContext(ctx, "SELECT * FROM users WHERE id = ?", id)
db.SetConnMaxLifetime 是防“陈旧连接”，不是防超时
这个方法控制连接复用寿命，和单次操作超时无关。它的作用是：让连接池定期淘汰老化连接，避免因数据库主动断连、中间件（如 ProxySQL、AWS RDS 代理）静默 kill 连接，导致后续 Query 报 driver: bad connection 或直接卡死。
典型配置建议：
-
db.SetConnMaxLifetime(30 * time.Second)：连接最多复用 30 秒，之后下次复用前会自动重连 -
db.SetMaxOpenConns(20)：防止突发流量打爆数据库（默认 0 = 无限制） -
db.SetMaxIdleConns(10)：空闲连接数上限，避免空耗资源（默认仅 2）
注意：SetConnMaxLifetime 不影响首次建连行为，也不能替代 QueryContext；它只在连接被取出复用前做存活判断。
HTTP handler 中怎么安全传递数据库超时 context
不能直接用 r.Context() 调 db.QueryContext，因为 r.Context() 的超时通常由 HTTP server 层统一设置（比如 30 秒），而 DB 查询应更短（比如 2–5 秒），且需独立控制。否则 DB 慢会导致整个 HTTP 请求超时，掩盖真实瓶颈。
推荐结构：
func userHandler(w http.ResponseWriter, r *http.Request) {
// 为 DB 操作单独设更紧的超时
dbCtx, dbCancel := context.WithTimeout(r.Context(), 3*time.Second)
defer dbCancel()
<pre class='brush:php;toolbar:false;'>rows, err := db.QueryContext(dbCtx, "SELECT name FROM users WHERE id = ?", userID)
if err != nil {
if errors.Is(err, context.DeadlineExceeded) {
http.Error(w, "DB timeout", http.StatusServiceUnavailable)
return
}
http.Error(w, "DB error", http.StatusInternalServerError)
return
}
// ...}
关键点：
- 不要把
dbCtx传给下游非 DB 操作（比如日志、缓存），避免误杀 - 检查
err时用errors.Is(err, context.DeadlineExceeded)，而非字符串匹配 - 别在 defer 里调
dbCancel()后还继续用dbCtx，否则可能 panic
事务中怎么控制超时边界
事务生命周期比单条语句长，超时必须覆盖整个事务块，而不是每条语句单独设。错误做法是给每个 tx.QueryContext 单独设 3 秒，结果整笔事务可能耗时 8 秒却没被中断。
正确方式：
- 在
db.BeginTx时就传入带超时的context - 后续所有
tx.QueryContext、tx.ExecContext都复用该context -
tx.Commit和tx.Rollback也必须用同一个context，否则提交阶段卡住无法感知
示例：
txCtx, txCancel := context.WithTimeout(r.Context(), 5*time.Second)
defer txCancel()
tx, err := db.BeginTx(txCtx, nil)
if err != nil { ... }
<p>_, err = tx.ExecContext(txCtx, "UPDATE accounts SET balance = ? WHERE id = ?", newBal, id)
if err != nil { tx.Rollback(); return }</p><p>err = tx.Commit() // 注意：这里也要用 txCtx
if err != nil { ... }最容易被忽略的是：事务提交本身也可能超时（比如二阶段提交、长事务锁等待），漏掉这一步，等于白设前面所有超时。
