Go database/sql Conn.PingContext 怎样检查专用连接是否仍可用

当业务代码拿到一条需要保持会话状态的数据库连接后，想知道它现在还能不能用，应该对这条 *sql.Conn 调用 PingContext，而不是把 *sql.DB 的连接池状态当成单条连接的结论。标准库文档把 Conn.PingContext 定义为检查该连接是否仍然存活；检查时要配合有截止时间的上下文，并在所有分支调用 Conn.Close。

这套写法解决的是“专用连接健康检查”，不是连接池容量调优，也不是驱动私有诊断接口。下面用一个具体的连接生命周期把边界拆开。

先区分 DB、Conn 和 PingContext

*sql.DB 是可并发使用的数据库句柄，内部管理连接池；db.Conn(ctx) 则从池中取得一条专用连接，同一条 *sql.Conn 上的查询会落在同一个数据库会话中。Conn.PingContext(ctx) 只回答这条专用连接当前是否仍可用。

获取专用连接并设置检查超时

先给获取连接和健康检查设置明确的截止时间。DB.Conn 本身可能因为连接池暂时没有可用连接而等待，所以只给 PingContext 设置超时还不够。

package main

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

// pingReservedConn 获取一条专用连接，并在有限时间内检查它是否仍可用。
func pingReservedConn(parent context.Context, db *sql.DB) error {
    // 这个截止时间同时约束等待连接和后续 PingContext。
    acquireCtx, cancel := context.WithTimeout(parent, 3*time.Second)
    defer cancel()

    conn, err := db.Conn(acquireCtx)
    if err != nil {
        // 获取阶段失败可能是上下文取消，也可能是驱动或连接池错误。
        return fmt.Errorf("get dedicated connection: %w", err)
    }
    // 无论 Ping 成功还是失败，都必须把专用连接归还连接池。
    defer conn.Close()

    if err := conn.PingContext(acquireCtx); err != nil {
        // 不把 Ping 失败误判成单一原因，调用方可继续检查 acquireCtx.Err()。
        return fmt.Errorf("ping dedicated connection: %w", err)
    }
    return nil
}

这里的顺序有两个重点：第一，db.Conn 和 PingContext 使用同一个带截止时间的上下文；第二，Conn.Close 用 defer 紧跟在成功获取之后。这样即使后续代码提前返回，也不会因为遗漏释放而长期占用连接池。

在 PingContext 返回后判断结果

PingContext 返回 nil，表示这次检查没有报告错误；返回非 nil 时，不要只根据错误字符串判断原因。先看检查上下文是否已经结束，再把原始错误保留下来交给上层日志或重试策略。

func checkConn(parent context.Context, conn *sql.Conn) error {
    // 健康检查应该有自己的时间预算，避免复用一个已接近截止的长上下文。
    pingCtx, cancel := context.WithTimeout(parent, 800*time.Millisecond)
    defer cancel()

    err := conn.PingContext(pingCtx)
    if err == nil {
        // nil 只说明本次 Ping 没有返回错误，不代表连接池中的所有连接都健康。
        return nil
    }

    if ctxErr := pingCtx.Err(); ctxErr != nil {
        // 截止时间或主动取消优先作为超时/取消信号记录。
        return fmt.Errorf("ping context ended: %w; ping error: %v", ctxErr, err)
    }
    // 上下文仍然有效时，保留驱动返回的原始错误供调用方分类。
    return fmt.Errorf("database connection is not ready: %w", err)
}

这段判断只做错误归类，不虚构某个驱动一定会返回的错误类型。不同驱动对网络断开、认证失效或服务端拒绝的包装方式可能不同；如果业务需要精确分类，应按所用驱动的官方文档处理。

检查结束后把 Conn 归还连接池

专用连接不是永久独占资源。官方文档要求每一条从 DB.Conn 得到的 Conn 最终调用 Close；关闭后，该连接上的后续操作会失败并返回 ErrConnDone。因此，健康检查失败也不能跳过释放。

func useAndRelease(parent context.Context, db *sql.DB) error {
    conn, err := db.Conn(parent)
    if err != nil {
        return err
    }

    // Close 会把 Conn 归还池中；即使后面的检查或业务查询失败也要执行。
    defer conn.Close()

    if err := checkConn(parent, conn); err != nil {
        return err
    }
    // 只有 Ping 成功后才继续使用这条固定会话连接。
    return nil
}

如果正在执行查询，Close 可以与其他操作并发调用，但它会等待其他操作结束。生产代码里更容易维护的方式仍然是：先取消或结束使用该连接的上下文，再在拥有者函数的退出路径统一关闭。

按场景选择 DB.PingContext 还是 Conn.PingContext

两者都叫 Ping，但检查对象不同：

• 应用启动或全局探活：使用 db.PingContext(ctx)，表达“这个数据库句柄当前能否完成一次连通性检查”。
• 固定会话前的检查：先用 db.Conn(ctx) 取得目标 Conn，再调用 conn.PingContext(ctx)，表达“这条专用连接是否还能用”。
• 连接获取超时：先检查 DB.Conn 的错误，因为连接池等待阶段还没有拿到可检查的 Conn。
• 检查失败：保留上下文错误和驱动原始错误，最后仍然执行 Conn.Close，不要把失败连接留在业务层引用里。

小结与常见追问

专用连接的最小安全组合是：用有截止时间的上下文调用 DB.Conn，成功后用 Conn.PingContext 检查，随后无论成功失败都调用 Conn.Close。这样检查的是目标会话，而不是把连接池级别的探活结果误当成单条连接结论。

为什么不用 db.PingContext 代替？因为它针对的是 *sql.DB 这个共享句柄，不能表达你刚刚拿到的那条 *sql.Conn 是否仍可用。

PingContext 返回错误后还要 Close 吗？要。只要 DB.Conn 成功返回了 Conn，就应在生命周期结束时归还它。

能否把 Conn 长期缓存起来反复 Ping？不建议把它当作永久连接。Conn 代表池中的单条资源，应该由明确的生命周期持有，并在不用时关闭。

上下文超时和数据库错误有什么区别？先看检查上下文的 Err，同时保留 PingContext 返回的原始错误；不要仅凭错误文本猜测驱动行为。

参考资料：database/sql DB.Conn、database/sql Conn.PingContext、database/sql Conn.Close。