Go database/sql 连接池上限与等待监控的配置方法

Go 的 database/sql 连接池配置，关键不是把最大连接数调到越大越好，而是让应用并发、数据库额度和请求超时处在同一个边界内。通常做法是全局复用一个 *sql.DB，先设置 SetMaxOpenConns，再用 SetMaxIdleConns、连接生命周期和 DBStats 控制与观察它。

官方资料：https://go.dev/doc/database/manage-connections

下面的示例把配置和监控放在一起。WaitCount、WaitDuration 是累计值，适合按时间窗口计算增量，不应该直接当作当前正在等待的请求数。

先把连接池参数和业务并发对齐

sql.Open 返回的是连接池句柄，不是已经建立的一条数据库连接。它应该在应用启动时创建一次，并传给需要访问数据库的服务。MaxOpenConns 限制同时打开的连接总数；达到上限后，新的操作会等待可用连接。MaxIdleConns 只控制空闲连接数量，不能替代打开连接上限。

package main

import (
    "context"
    "database/sql"
    "fmt"
    "time"
)

func openDB(dsn string) (*sql.DB, error) {
    // sql.Open 创建可复用的池句柄；真正连通性由 PingContext 检查。
    db, err := sql.Open("mysql", dsn)
    if err != nil {
        return nil, err
    }

    // 上限应低于数据库为该服务预留的连接额度，并留出管理连接余量。
    db.SetMaxOpenConns(32)
    // 空闲连接不宜超过打开上限，避免突发流量前后保留过多资源。
    db.SetMaxIdleConns(8)
    // 定期轮换连接，降低服务端网络设备或数据库连接老化的影响。
    db.SetConnMaxLifetime(30 * time.Minute)
    db.SetConnMaxIdleTime(5 * time.Minute)

    ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
    defer cancel() // 超时后释放 PingContext 持有的等待资源。
    if err := db.PingContext(ctx); err != nil {
        db.Close() // 初始化失败时关闭池，避免留下半初始化资源。
        return nil, fmt.Errorf("ping database: %w", err)
    }
    return db, nil
}

参数没有通用固定值。可以先从业务实例的并发请求量、单次 SQL 持续时间和数据库允许的连接数倒推，再观察等待指标。连接生命周期也不应短到让每个请求都频繁重建连接；如果数据库或代理有更短的连接存活限制，再把应用侧的轮换时间留出余量。

用 DBStats 定位等待与容量不足

只看数据库报错往往无法判断问题在应用侧。db.Stats() 可以提供当前打开数、使用中数量、空闲数量以及等待累计时间。把两个采样点的累计值相减，就能得到这段时间新增的等待次数与等待时长。

type PoolSnapshot struct {
    Open         int
    InUse        int
    Idle         int
    WaitCount    int64
    WaitDuration time.Duration
}

func snapshot(db *sql.DB) PoolSnapshot {
    // Stats 返回当前池状态与累计等待计数，读取本身不会执行 SQL。
    stats := db.Stats()
    return PoolSnapshot{
        Open:         stats.OpenConnections,
        InUse:        stats.InUse,
        Idle:         stats.Idle,
        WaitCount:    stats.WaitCount,
        WaitDuration: stats.WaitDuration,
    }
}

func diff(before, after PoolSnapshot) (int64, time.Duration) {
    // 用相邻采样点计算窗口增量，避免把累计值误读成单次请求结果。
    return after.WaitCount - before.WaitCount,
        after.WaitDuration - before.WaitDuration
}

排查时先看三个组合：Open 接近 MaxOpenConns 且等待增量持续增加，说明并发峰值可能超过池上限；InUse 长时间不降而 Idle 接近零，要检查 rows、事务和请求取消后的归还路径；等待增量很小但数据库响应很慢，则应转向 SQL、锁或数据库本身，而不是继续增大连接数。

上线前的连接归还检查清单

连接池参数调大之前，先确认每个 QueryContext 返回的 Rows 都会关闭，事务在成功和失败路径都有提交或回滚，长 SQL 使用带截止时间的上下文。对单行查询也要处理 sql.ErrNoRows，不要因为业务分支遗漏而让请求一直持有资源。

调参采用一次只改一个变量的方式：记录每分钟请求量、P95 延迟、数据库连接数和等待增量，观察一个完整业务高峰，再决定是否继续。MaxOpenConns 过小会排队，过大则可能把压力直接推给数据库；监控与回滚参数必须一起上线。

常见问题

MaxIdleConns 可以设置得比 MaxOpenConns 大吗？ 可以调用，但实际空闲连接数不会超过当前打开连接上限。为了避免配置含义混乱，通常让空闲上限小于或等于打开上限。

WaitCount 增长就一定是连接池泄漏吗？ 不一定。短时突发并发会正常产生等待；只有结合 InUse 长时间不降、rows 或事务没有释放，才更像泄漏，应先检查归还路径。