database/sql Conn.Raw 执行驱动级操作的边界

在 Go 服务里，database/sql 已经把连接池、事务和参数传递封装得很好，但有时数据库驱动还提供了连接级能力：设置会话属性、读取驱动专属状态，或调用标准接口没有覆盖的功能。这时可以使用 Conn.Raw。

它的关键不是“拿到一个更底层的连接”，而是在一个很短的回调里借用底层连接。回调结束后，驱动连接就不能再被业务代码保存、异步使用或交给另一个 goroutine。只要把这个边界守住，Raw 是一个窄而实用的适配点；一旦把它当成长期句柄，连接池和并发问题就会一起出现。

先把三层连接关系分清

sql.DB 是连接池入口，适合并发执行普通查询；sql.Conn 代表从池里借到的一条会话连接，适合需要连续会话状态的场景；回调参数中的 driverConn 则是驱动实现自己的连接对象。

官方文档对 Raw 的定义很明确：它在回调持续期间暴露底层驱动连接，驱动连接不能在回调外使用。回调返回后，如果错误不是 driver.ErrBadConn，这个 sql.Conn 仍可继续使用；如果是坏连接错误，database/sql 会把连接视为不可复用的对象。

因此，Raw 解决的是“标准抽象缺少一个窄入口”，不是“让业务代码绕开连接池自行管理连接”。

适用压力：标准接口确实不够用

一个具体场景是：应用要给当前会话设置驱动支持的连接级参数，但这个动作并不适合拼成普通 SQL，也没有对应的 database/sql 方法。此时可以先从 DB.Conn 获得会话连接，再把一次驱动调用封装在 Raw 中。

注意，先拿 sql.Conn 本身就可能等待连接池。这个等待是有意的，因为后面的驱动级操作必须落在同一条数据库会话上。给它配合可取消的上下文，并且在函数返回前关闭它：

package main

import (
    "context"
    "database/sql"
    "database/sql/driver"
    "errors"
    "fmt"
)

// runDriverOperation 只把底层连接借给回调，调用方拿不到长期句柄。
func runDriverOperation(ctx context.Context, db *sql.DB) error {
    // Conn 可能等待池中有可用连接，因此让 ctx 控制等待时间。
    conn, err := db.Conn(ctx)
    if err != nil {
        return fmt.Errorf("get sql connection: %w", err)
    }
    // Close 会把 sql.Conn 归还连接池；它会等待正在进行的操作结束。
    defer conn.Close()

    err = conn.Raw(func(driverConn any) error {
        // 这里应断言到目标驱动公开的连接接口，而不是依赖未导出的具体类型。
        session, ok := driverConn.(interface {
            SetSessionOption(context.Context, string, string) error
        })
        if !ok {
            return fmt.Errorf("driver does not expose session option")
        }

        // 驱动级调用必须在这个回调内完成，不能把 session 保存到外部。
        return session.SetSessionOption(ctx, "timezone", "UTC")
    })
    if err != nil {
        // 保留底层错误链，调用方可用 errors.Is 做分类处理。
        return fmt.Errorf("set driver session option: %w", err)
    }
    return nil
}

var _ = driver.ErrBadConn
var _ = errors.Is

示例中的接口是为了表达适配边界而定义的抽象，具体驱动是否提供同名能力要以驱动自己的公开文档为准。文章的重点是调用位置和生命周期，而不是虚构一个通用驱动 API。

典型实现：回调里完成一次闭环

把 Raw 代码写成“打开、操作、返回”的小闭环，通常比在回调里启动 goroutine 更安全。回调内可以做类型断言、调用驱动接口、转换错误并返回结果；回调外只保留业务层需要的值，例如字符串、数值或一个已经复制出来的结构体。

错误处理尤其要保留 driver.ErrBadConn 的语义。如果驱动明确返回这个错误，不要把它吞掉后继续把这条连接交给后续逻辑。可以用 errors.Is 判断是否属于坏连接，再决定记录指标或触发上层重试：

func inspectRaw(ctx context.Context, conn *sql.Conn) (string, error) {
    var state string
    err := conn.Raw(func(driverConn any) error {
        // 只在回调内使用 driver.Conn，返回前把需要的结果复制到 state。
        inspector, ok := driverConn.(interface {
            SessionState(context.Context) (string, error)
        })
        if !ok {
            return fmt.Errorf("driver session inspection is unsupported")
        }
        value, err := inspector.SessionState(ctx)
        if err != nil {
            // 不改写 driver.ErrBadConn，让 database/sql 识别坏连接。
            return err
        }
        state = value
        return nil
    })
    if err != nil {
        if errors.Is(err, driver.ErrBadConn) {
            return "", fmt.Errorf("driver connection is unusable: %w", err)
        }
        return "", err
    }
    return state, nil
}

这里的 state 是普通字符串，回调结束后仍然有效；inspector 只是回调内部的借用视图。若驱动接口返回的是引用底层缓冲区的对象，则需要按照驱动文档复制数据后再带出回调。

最容易踩中的两个反例

反例一：把 driver.Conn 保存到结构体

回调里把参数赋给全局变量、缓存字段或返回闭包，看起来像是“复用连接”，实际上是在延长一个只允许短暂借用的对象的生命周期。下一次连接池调度、回调返回或连接失效后，这个引用就没有可靠的使用契约。

更稳妥的方式是把驱动调用封装在一个函数中，函数签名只返回业务数据和错误。这样代码审查时能直接看到底层连接没有穿过适配层。

反例二：在 Raw 回调里启动异步任务

下面这种写法的问题不在于 goroutine 本身，而在于 goroutine 运行时回调可能已经返回：

func badAsync(conn *sql.Conn) error {
    return conn.Raw(func(driverConn any) error {
        go func() {
            // 错误：goroutine 可能在 Raw 返回后继续使用 driverConn。
            _ = driverConn
        }()
        return nil
    })
}

如果确实需要异步执行，应在回调内同步完成驱动操作，把结果复制成独立值，再把这个值交给后续 goroutine。底层连接对象不应成为异步任务的输入。

连接占用和并发后果

sql.DB.Conn 返回的连接需要调用 Close 才能回到池里。遗漏关闭会让池中的可用连接减少，最终表现为后续请求在 DB.Conn 处排队。即使 Raw 本身很短，外层函数如果持有 sql.Conn 很久，也会让这个会话持续占用池资源。

驱动层的 driver.Conn 还假定不会被多个 goroutine 并发使用。不要把 Raw 当成绕过这一约束的通道；如果多个业务任务都需要驱动能力，应让每个任务通过 sql.DB 或明确的 sql.Conn 生命周期进入，而不是共享一个底层句柄。

一个实际的封装通常应该满足这几个条件：

• 入口接收 context.Context，连接池等待和驱动调用都能被取消。
• 函数内部获取 *sql.Conn，并在同一作用域中 defer Close。
• Raw 回调只做一次短操作，不启动依赖底层句柄的异步任务。
• 错误使用 %w 保留原因，特别是不要吞掉 driver.ErrBadConn。
• 只把复制后的业务数据带出回调，绝不返回驱动私有连接或其引用。

什么时候不该使用 Conn.Raw

如果普通查询、事务、预处理语句和会话级连续性已经能满足需求，就继续使用 database/sql 的公共接口。Raw 会把代码和具体驱动绑在一起，也会让连接生命周期更容易被误解。

可以用下面的判断清单收尾：

一句话概括：Conn.Raw 是“在回调内借用驱动连接”的窄接口，不是把驱动连接所有权交给业务代码。把借用范围、错误语义和 Close 归还动作写在同一个小函数里，才能让这个低层能力保持可控。

相关资料

Go 官方 database/sql 文档：https://pkg.go.dev/database/sql

Go 官方 database/sql/driver 文档：https://pkg.go.dev/database/sql/driver

常见追问

Conn.Raw 会自动关闭底层 driver.Conn 吗？

Raw 负责限定回调可见范围，不替代 sql.Conn.Close。外层借到的 sql.Conn 仍然要显式关闭，让连接回到池中。

Raw 回调返回 driver.ErrBadConn 后还能继续用 sql.Conn 吗？

不要继续把它当作健康连接使用。该错误用于告诉 database/sql 当前底层连接不可复用，应该让上层按坏连接处理。

可以从 Raw 回调返回驱动的具体连接类型吗？

不建议。这样会把驱动私有类型和生命周期带到业务层；更好的做法是在回调中转换成公开的业务结果或自定义适配层结果。