database/sql 是 Go 标准库提供的关系型数据库抽象层，它的核心价值不在于帮你生成 SQL，而在于统一了不同驱动的调用方式，并在底层维护连接池。实际项目中很多数据库相关问题并不是 SQL 写错，而是连接管理方式不正确。比如把 sql.Open 放在每个请求处理函数里，或者从不设置连接池上限，最终导致数据库连接数被打满。还有的代码查询完后忘记关闭 rows，或者事务既不提交也不回滚，连接一直被占用。这篇文章从初始化和连接管理的角度，把常见的坑梳理一遍。

一、初始化 sql.DB：单例与驱动注册

database/sql 本身不实现任何具体数据库协议，它通过驱动适配。使用前需要引入驱动包，例如 MySQL 驱动 github.com/go-sql-driver/mysql，通常用空白导入方式注册：

import (
    "database/sql"
    _ "github.com/go-sql-driver/mysql"
)

空白导入会执行驱动的 init 函数，调用 sql.Register 注册驱动名。随后调用 sql.Open("mysql", dsn) 时，database/sql 根据驱动名找到对应实现。很多人误以为 sql.Open 会建立连接，实际上它只做参数校验并返回一个 *sql.DB 对象。这个对象内部维护连接池，物理连接是按需创建的。因此初始化阶段不会因为数据库不可达而报错，只有真正查询时才会暴露。

初始化后应使用 PingContext 探测网络和服务端，这样可以在启动阶段发现配置错误，而不是等到第一个请求超时：

db, err := sql.Open("mysql", "user:pass@tcp(127.0.0.1:3306)/dbname?parseTime=true")
if err != nil {
    log.Fatal(err)
}
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
if err := db.PingContext(ctx); err != nil {
    log.Fatal(err)
}

*sql.DB 需要全局复用，不要在每次请求或业务方法中重新 sql.Open。多次 sql.Open 会创建多个连接池，它们互相独立，无法统一限制总量；同时频繁创建销毁对象也会增加 GC 压力。正确的做法是在 main 或依赖注入阶段初始化一次，然后以参数或全局变量形式传给各个模块。sql.DB 是并发安全的，可以被多个 goroutine 安全使用。

二、连接池参数：给资源加上边界

database/sql 的连接池默认行为比较宽松：最大打开连接数不受限制，最大空闲连接数默认是 2，连接最大生命周期不限制。在生产环境中，如果不设置 SetMaxOpenConns，一旦请求量突增，连接池会不断向数据库建立新连接，直到数据库上限。这也是 too many connections 最常见的来源之一。因此初始化后应显式设置四个关键参数：

db.SetMaxOpenConns(64)
db.SetMaxIdleConns(32)
db.SetConnMaxLifetime(10 * time.Minute)
db.SetConnMaxIdleTime(2 * time.Minute)

SetMaxOpenConns 控制同时打开多少个物理连接，超过这个数后请求会阻塞等待，而不是无限创建。SetMaxIdleConns 表示池中最多保留多少个空闲连接，太小会导致频繁建连，太大会占用数据库会话。SetConnMaxLifetime 限制连接从创建到关闭的最大时间，避免服务端主动断开后客户端还复用过期连接，MySQL 的 wait_timeout 通常为 8 小时，客户端生命周期应小于这个值。SetConnMaxIdleTime 控制空闲连接判定为可关闭的时长，帮助在低峰期释放资源。

参数取值不能拍脑袋，要结合数据库配置和压测。比如云数据库连接数上限可能是 200，应用实例有 4 个，那么每个实例最大打开连接控制在 40 左右比较安全，留出运维和迁移余量。空闲连接数通常设为最大打开连接的一半到四分之一。可以通过监控连接池指标和数据库 SHOW PROCESSLIST 观察实际使用情况，逐步调整。

另外注意连接池的等待行为：当连接数达到 SetMaxOpenConns 后，新查询会阻塞等待直到有连接释放或上下文超时。如果查询都在 100ms 内完成，短暂等待可以接受；但如果慢查询占满连接，后续请求会大量堆积。所以连接池参数只是最后一道防线，真正要解决的是慢 SQL 和事务过长问题。

三、用 Context 控制查询与事务

Go 标准库从 1.8 开始为查询和事务提供带 Context 的方法，例如 QueryContext、ExecContext、PrepareContext 和 BeginTx。相比不带 Context 的方法，它们能传递超时、取消信号和请求级元数据。建议所有在线请求都使用 Context，不要使用 db.Query 这类旧接口。

func GetUserName(ctx context.Context, db *sql.DB, id int) (string, error) {
    var name string
    row := db.QueryRowContext(ctx, "SELECT name FROM users WHERE id = ?", id)
    if err := row.Scan(&name); err != nil {
        return "", err
    }
    return name, nil
}

外部传入的 ctx 通常来自 HTTP 请求或 gRPC，当客户端断开或超时时，context 会自动取消，数据库驱动收到取消信号后中断等待。如果没有这个机制，一个慢查询可能持续占用连接直至数据库超时，浪费资源。

事务必须显式提交或回滚。推荐模式是用 defer tx.Rollback() 保证异常路径不会泄漏事务：

func UpdateOrderStatus(ctx context.Context, db *sql.DB, orderID int) error {
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }
    defer tx.Rollback()
    _, err = tx.ExecContext(ctx, "UPDATE orders SET status = 'paid' WHERE id = ?", orderID)
    if err != nil {
        return err
    }
    return tx.Commit()
}

Rollback 在事务已提交后调用会返回 sql.ErrTxDone，不影响正常路径。因此 defer 写法安全。事务的上下文要与查询保持一致，不要在事务内部使用独立超时更短的 Context，否则外层可能提前结束导致提交失败。

另外避免在事务中做外部 I/O 或耗时计算。事务持有连接直到提交或回滚，如果中间调用 HTTP 接口或做复杂计算，连接占用时间被拉长，会直接降低连接池吞吐。

四、连接泄漏的排查与避免

连接泄漏通常表现为：服务运行一段时间后数据库连接数缓慢上涨，重启后恢复，然后继续上涨。常见泄漏点有三个：查询结果集未关闭、事务未结束、以及 sql.Stmt 未关闭。

使用 db.QueryContext 返回 *sql.Rows 后，必须在使用完调用 rows.Close()。如果提前返回，可以用 defer rows.Close()；注意 Close 不是幂等操作，但多次调用安全。示例：

rows, err := db.QueryContext(ctx, "SELECT id, name FROM users")
if err != nil {
    return err
}
defer rows.Close()
for rows.Next() {
    var id int
    var name string
    if err := rows.Scan(&id, &name); err != nil {
        return err
    }
    fmt.Println(id, name)
}
return rows.Err()

rows 持有底层连接，直到 Close 或遍历到结尾后自动关闭。但提前 return 没有 defer 会泄漏。另一个坑是循环中 return，如果 defer rows.Close() 已经设置，则安全。

事务未结束也会泄漏连接。如果只 BeginTx 不提交不滚，连接会一直被占用。代码审查时可以关注 BeginTx 后是否有 Commit 或 Rollback。预编译语句 Prepare 同理，使用后需要 Stmt.Close()。

排查时可以用数据库 SHOW PROCESSLIST 查看连接来源、状态和 SQL，也可以使用 database/sql 的 DB.Stats() 获取连接状态：

stats := db.Stats()
fmt.Printf("Open=%d InUse=%d Idle=%d WaitCount=%d\n",
    stats.OpenConnections, stats.InUse, stats.Idle, stats.WaitCount)

OpenConnections 表示已打开的物理连接数量，InUse 是正在使用的连接，Idle 是空闲连接，WaitCount 记录有多少请求因为连接池满而等待。如果 InUse 长时间接近 MaxOpenConns，说明并发查询接近上限，需要考虑优化查询或扩容。

数据库连接管理并不复杂，核心只有两点：一个进程一个 sql.DB，四个池参数按容量设置；所有查询和事务都带上 Context 并正确释放资源。做到这两点，too many connections 这类问题基本不会出现。