4. Go database/sql 接口概览：sql.DB、sql.Conn、sql.Stmt、sql.Rows 核心对象与生命周期

在 Go 语言中，database/sql 标准库是操作关系型数据库的基石。无论是原生 SQL 还是 ORM 框架（如 GORM、Ent），底层最终都依赖该接口与数据库交互。理解其核心对象及其生命周期，是进行慢查询诊断与连接池水位监控的前提。

本章将逐一剖析 sql.DB、sql.Conn、sql.Stmt、sql.Rows 四个核心对象，并梳理它们从创建到销毁的完整生命周期。

4.1 核心对象一览

4.2 对象生命周期与交互流程

下图展示了在一次典型查询场景中，四个核心对象的创建顺序与依赖关系：

4.3 各对象深度解析

4.3.1 sql.DB — 连接池管理器

sql.DB 是应用与数据库交互的入口。它内部维护了一个连接池，包含空闲连接（freeConn）和等待队列（connRequests）。

• 创建： sql.Open(driverName, dataSourceName) 仅初始化池结构，不会立即建立连接。首次实际连接在第一次查询时懒加载。
• 配置：
  • SetMaxOpenConns(n) — 最大打开连接数（含正在使用的）
  • SetMaxIdleConns(n) — 最大空闲连接数
  • SetConnMaxLifetime(d) — 连接最大存活时间
  • SetConnMaxIdleTime(d) — 连接最大空闲时间（Go 1.15+）
• 协程安全： 是。多个 goroutine 可安全并发调用 db.Query()、db.Exec() 等方法。
• 关闭： db.Close() 关闭所有连接，通常只在应用退出时调用。

4.3.2 sql.Conn — 独占连接

sql.Conn 代表一个从池中取出的、独占的底层连接。它绕过了连接池的自动复用逻辑，适用于需要事务隔离或设置会话级别变量的场景。

• 创建： db.Conn(ctx) 从池中获取一个连接。如果池中无空闲连接且已达 MaxOpenConns，调用会阻塞直到有连接归还或超时。
• 使用： 可执行 conn.ExecContext()、conn.QueryContext()、conn.PrepareContext()。
• 归还： 必须调用 conn.Close() 将连接归还到池中。忘记关闭会导致连接泄漏，最终耗尽连接池。
• 协程安全： 否。同一时刻只能由一个 goroutine 使用。

4.3.3 sql.Stmt — 预编译语句

预编译语句将 SQL 解析和执行计划缓存在数据库端，多次执行时只需传递参数，显著提升性能并防止 SQL 注入。

• 创建：
  • db.Prepare(query) — 从池中取一个连接进行预编译，返回的 Stmt 内部会记住该连接。
  • conn.Prepare(query) — 在指定连接上预编译，返回的 Stmt 只能在该连接上执行。
• 执行： stmt.Exec(args)、stmt.Query(args)、stmt.QueryRow(args)。
• 关闭： stmt.Close() 释放预编译语句资源。如果 Stmt 由 db.Prepare() 创建，关闭后不会关闭底层连接。
• 协程安全： 是。多个 goroutine 可并发执行同一个 Stmt。

4.3.4 sql.Rows — 结果集游标

sql.Rows 是查询结果集的迭代器。它从数据库逐行拉取数据，直到遍历完毕或主动关闭。

• 创建： db.Query()、stmt.Query()、conn.QueryContext()。
• 遍历： 使用 rows.Next() 循环判断是否有下一行，rows.Scan(dest...) 将当前行数据扫描到目标变量。
• 关闭： 必须调用 rows.Close()。即使遍历完所有行，也应显式关闭以释放底层连接。未关闭的 Rows 会一直持有连接，导致连接池耗尽。
• 协程安全： 否。同一时刻只能由一个 goroutine 遍历。

// 标准使用模式
rows, err := db.QueryContext(ctx, "SELECT id, name FROM users WHERE age > ?", 18)
if err != nil {
    log.Fatal(err)
}
defer rows.Close() // 确保关闭

for rows.Next() {
    var id int
    var name string
    if err := rows.Scan(&id, &name); err != nil {
        log.Fatal(err)
    }
    // 处理行数据
}
if err := rows.Err(); err != nil {
    log.Fatal(err) // 检查遍历过程中的错误
}

4.4 生命周期对比总结

4.5 生命周期中的常见错误模式

1. Rows 未关闭： 忘记 defer rows.Close() 或在错误路径中未关闭，导致连接被长期占用。
2. Conn 未归还： 使用 db.Conn() 后忘记 Close()，连接从池中永久移除。
3. Stmt 泄漏： 在循环中反复 db.Prepare() 而不 Close()，导致数据库端预编译缓存膨胀。
4. DB 重复创建： 每次请求都 sql.Open()，产生大量独立连接池，耗尽系统文件描述符。