Go database/sql 怎样用 Connector 统一连接配置

当数据库驱动已经提供了 driver.Connector，可以把它交给 sql.OpenDB，而不是把 DSN 字符串再次交给 sql.Open。这样，驱动负责连接配置和建立底层连接，*sql.DB 负责并发安全的数据库句柄与连接池。

官方文档：https://pkg.go.dev/database/sql；驱动接口：https://pkg.go.dev/database/sql/driver

Connector 是“怎样创建底层连接”的配置入口，*sql.DB 是“怎样复用和管理连接”的上层句柄。使用 OpenDB 后仍然要保存并在合适的生命周期结束时调用 DB.Close()。

先分清 Open 与 OpenDB 的入口差异

sql.Open(driverName, dataSourceName) 适合把驱动名和 DSN 字符串交给 database/sql，而 sql.OpenDB(connector) 直接接收驱动实现的 driver.Connector。后者适合驱动已经把 DSN 解析、认证配置或连接创建逻辑封装起来的场景。

两种入口返回的都是 *sql.DB，也都不是“立刻建立一条数据库连接”的函数。*sql.DB 会在后续查询、Ping 或事务操作需要时管理连接。区别在于配置从哪里进入：

所以，OpenDB 不是把一个现有连接包装成 *sql.DB，也不是绕过连接池。它是让 database/sql 从 Connector 创建和管理底层连接。

从驱动配置创建 Connector

Connector 接口位于 database/sql/driver，包含 Connect(context.Context) 和 Driver()。具体驱动通常提供自己的构造函数；标准库只规定接口，不规定每个驱动如何解析配置。

下面用一个抽象的 newConnector 表示驱动提供的构造函数。实际项目中应替换成所用驱动的官方 API，并把构造失败当成启动阶段错误处理：

package main

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

// newConnector 代表具体驱动提供的 Connector 构造函数。
// 它不属于 database/sql，真实代码应调用目标驱动的官方实现。
func newConnector(_ string) (driver.Connector, error) {
	return nil, fmt.Errorf("请替换为具体驱动的 Connector 构造函数")
}

func openWithConnector(dsn string) (*sql.DB, error) {
	// 先由驱动解析 DSN，避免把驱动专属配置塞进业务层。
	connector, err := newConnector(dsn)
	if err != nil {
		return nil, fmt.Errorf("创建 Connector 失败: %w", err)
	}

	// OpenDB 创建的是数据库句柄；底层连接按需由 database/sql 管理。
	db := sql.OpenDB(connector)
	return db, nil
}

func closeDB(ctx context.Context, db *sql.DB) error {
	// Close 负责释放句柄持有的资源；ctx 用于业务操作，不替代 Close。
	_ = ctx
	return db.Close()
}

示例中的 newConnector 只是边界示意，不应直接运行。关键点是：Connector 的创建错误在得到 *sql.DB 前返回，sql.OpenDB 本身返回 *sql.DB，后续连接建立失败则应在 PingContext、查询或事务调用处处理。

用 OpenDB 创建连接池

拿到 *sql.DB 后，查询代码不需要接触 Connector。应用可以像使用普通 *sql.DB 一样调用 QueryContext、ExecContext 或 BeginTx。请求级超时仍应放在传给这些方法的 context.Context 中。

func loadUser(ctx context.Context, db *sql.DB, id int64) error {
	// 请求上下文控制这一次查询的取消和超时，不修改全局连接配置。
	row := db.QueryRowContext(ctx,
		"SELECT name FROM users WHERE id = ?", id,
	)

	var name string
	// Scan 的错误必须返回给调用方，不能把连接或查询失败当成空结果。
	if err := row.Scan(&name); err != nil {
		return fmt.Errorf("读取用户 %d 失败: %w", id, err)
	}
	fmt.Println(name)
	return nil
}

连接池参数属于 *sql.DB 的运行时管理边界，例如 SetMaxOpenConns、SetMaxIdleConns 和 SetConnMaxLifetime。Connector 提供的是创建底层连接所需的配置，不等于池参数。

复用配置但隔离多个连接池

如果一个进程需要两个用途不同的数据库句柄，可以让它们各自调用 sql.OpenDB，并分别设置池参数。这样共享的是 Connector 所代表的驱动配置，隔离的是每个 *sql.DB 自己维护的连接池和关闭生命周期。

func openPools(connector driver.Connector) (*sql.DB, *sql.DB) {
	// 每次 OpenDB 都创建独立的 *sql.DB 管理边界和连接池。
	businessDB := sql.OpenDB(connector)
	reportDB := sql.OpenDB(connector)

	// 两套池的并发需求不同，分别设置，不把 Connector 当成池配置。
	businessDB.SetMaxOpenConns(30)
	reportDB.SetMaxOpenConns(5)
	return businessDB, reportDB
}

func closePools(businessDB, reportDB *sql.DB) error {
	// 谁创建 *sql.DB，谁负责在生命周期结束时关闭对应句柄。
	if err := reportDB.Close(); err != nil {
		return fmt.Errorf("关闭报表库失败: %w", err)
	}
	if err := businessDB.Close(); err != nil {
		return fmt.Errorf("关闭业务库失败: %w", err)
	}
	return nil
}

是否可以把同一个 Connector 传给多个 OpenDB，还要看具体驱动对 Connector 的实现是否允许并发调用和重复使用；如果驱动文档明确要求每个句柄一个 Connector，就按驱动约束分别创建。不要把“配置可复用”误解成“所有驱动都保证 Connector 任意共享”。

把超时和关闭动作放在边界

Connector、*sql.DB 和请求上下文分别解决不同问题：Connector 描述底层连接如何创建，*sql.DB 管理连接池，请求上下文控制单次操作取消。把三者混用，常见结果是把一次慢查询误当成全局连接配置问题。

func queryWithTimeout(parent context.Context, db *sql.DB) error {
	// 只给本次查询设置截止时间，结束后释放定时器资源。
	ctx, cancel := context.WithTimeout(parent, 2*time.Second)
	defer cancel()

	// 超时会通过 ctx 传给驱动，调用方仍需检查返回错误。
	_, err := db.ExecContext(ctx, "UPDATE jobs SET state = ? WHERE id = ?", "done", 1)
	if err != nil {
		return fmt.Errorf("更新任务失败: %w", err)
	}
	return nil
}

服务退出时，在拥有 *sql.DB 的组件边界调用 Close。如果还需要等待正在执行的业务操作，应先停止接收新请求，再按应用自己的退出顺序等待，最后关闭数据库句柄；不要期待 Connector 替代整个应用的优雅退出协调。

常见问题

OpenDB 会立即验证数据库地址吗？

不应把 OpenDB 当成连通性探测。需要启动时确认连接时，可以显式调用 PingContext 并处理错误；查询和事务也必须检查各自返回值。

Connector 和连接池参数是一回事吗？

不是。Connector 负责让驱动创建底层连接，SetMaxOpenConns 等方法作用于返回的 *sql.DB 连接池。

多个 OpenDB 得到的 DB 可以互相替代吗？

它们都是 *sql.DB，但可能拥有不同连接池、并发限制和关闭生命周期。是否使用同一个 Connector，还要遵守具体驱动的实现约束。

为什么还要给查询传 context？

Connector 的连接配置是长期边界，QueryContext 或 ExecContext 的 context 是单次操作边界；后者才能表达请求取消与查询超时。

最小记忆点是：驱动负责提供 Connector，sql.OpenDB 把 Connector 接入 database/sql，返回的每个 *sql.DB 负责自己的连接池。配置复用、池参数隔离、请求超时和关闭动作分别放在各自边界，代码会更容易维护。