Go问答：database/sql/driver.DriverContext 怎样让驱动按 DSN 创建连接

如果一个 Go 数据库驱动需要按 DSN 延迟创建连接，并且希望连接建立过程能响应取消或超时，推荐把连接参数放进 database/sql/driver.Connector，让实现了 driver.DriverContext 的驱动通过 OpenConnector 返回它。真正建立底层连接时，再由 Connector.Connect(ctx) 使用请求上下文。

关键点是：OpenConnector 只负责把 DSN 变成可复用的连接器，Connect(ctx) 才负责创建一次具体连接并处理取消。不要在 OpenConnector 里提前打开连接，也不要丢掉 ctx。

官方地址：https://pkg.go.dev/database/sql/driver#DriverContext

Connector 接口：https://pkg.go.dev/database/sql/driver#Connector

一、先看三层关系：Driver、Connector 和 Conn

database/sql 面向的是 driver.Driver，驱动作者则需要把 DSN、连接器和底层连接的职责拆开。DriverContext 是在 Driver 基础上增加 OpenConnector(name string) 的接口；返回的 Connector 保存建立连接所需的配置，Connect(ctx) 每次返回一个新的 driver.Conn。

因此可以把生命周期理解为：DSN 是输入，Connector 是可复用的配置对象，Conn 是一次实际打开的连接。连接池可能多次调用 Connect(ctx)，所以 Connector 本身不应保存某一次连接的可变状态。

二、在 OpenConnector 中保存 DSN，而不是打开连接

最小实现可以先把 DSN 做必要的空值检查，再把它封装进连接器。下面的 openConn 代表驱动自己的连接创建函数，它最终需要返回完整实现 driver.Conn 的对象。

package example

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

type driverImpl struct{}

type connectorImpl struct {
	dsn string // 保存 DSN，不在这里创建具体连接
}

// OpenConnector 只解析并保存连接配置，便于 database/sql 后续复用。
func (driverImpl) OpenConnector(name string) (driver.Connector, error) {
	if strings.TrimSpace(name) == "" {
		return nil, errors.New("empty DSN") // 配置错误应在入口尽早返回
	}
	return connectorImpl{dsn: name}, nil
}

// Connect 负责创建一次具体连接；openConn 应返回实现 driver.Conn 的对象。
func (c connectorImpl) Connect(ctx context.Context) (driver.Conn, error) {
	select {
	case <-ctx.Done():
		return nil, ctx.Err() // 建连前先响应取消或超时
	default:
	}
	return openConn(ctx, c.dsn)
}

// Driver 仍需实现 Open；下面的兼容实现见后文。
func (driverImpl) Open(name string) (driver.Conn, error) {
	return openConn(context.Background(), name)
}

var _ driver.Driver = driverImpl{}
var _ driver.DriverContext = driverImpl{}

这里的重点不是把 DSN 拆成多少字段，而是不要让 OpenConnector 产生网络连接。这样同一个 Connector 可以被 database/sql 用于不同的连接创建时机，错误也能区分为“配置错误”和“本次建连错误”。

三、在 Connect(ctx) 中真正建连并传递上下文

Connect(ctx) 的 ctx 只覆盖当前连接创建过程。驱动如果还要支持查询取消，需要在返回的 driver.Conn 以及对应的上下文接口中继续实现取消语义；不能把一次建连的上下文保存成连接的永久字段。

func (c connectorImpl) Connect(ctx context.Context) (driver.Conn, error) {
	// 先检查调用方是否已经取消，避免无意义地拨号。
	if err := ctx.Err(); err != nil {
		return nil, err
	}

	// 真实驱动应在 openConn 内部把 ctx 传给拨号、认证和握手逻辑。
	conn, err := openConn(ctx, c.dsn)
	if err != nil {
		return nil, err // 保留底层错误，便于上层判断建连失败原因
	}
	return conn, nil
}

如果底层网络库只接受地址而不接受上下文，至少要在它外层配合可取消的拨号器；仅在函数开头检查一次 ctx.Err()，无法中断已经开始的阻塞拨号。成功返回后，Connector 不应再修改连接对象的配置。

还要注意 Connector.Driver()：它应返回创建该 Connector 的 Driver。这个方法用于让 database/sql 识别连接器所属驱动，不应临时构造另一个带不同配置的 Driver。

func (c connectorImpl) Driver() driver.Driver {
	// 返回同一类驱动实例，保持 Connector 与 Driver 的归属一致。
	return driverImpl{}
}

四、交给 database/sql 的两种方式

如果手里已经有 Connector，可以直接使用 sql.OpenDB。这种方式适合调用方需要显式持有不同 DSN 的 Connector；如果希望通过驱动名打开，则注册实现了 DriverContext 的 Driver，再调用 sql.Open。

import (
	"database/sql"
)

func openWithConnector(ctx context.Context, dsn string) (*sql.DB, error) {
	// OpenConnector 不建立网络连接，只返回保存 DSN 的 Connector。
	connector, err := (driverImpl{}).OpenConnector(dsn)
	if err != nil {
		return nil, err
	}

	// OpenDB 接管 DB 生命周期；调用方必须负责 Close。
	db := sql.OpenDB(connector)
	if err := db.PingContext(ctx); err != nil {
		db.Close() // 初始化失败时立即释放 DB 及可能创建的连接
		return nil, err
	}
	return db, nil
}

sql.OpenDB 返回的 *sql.DB 仍然是连接池，不代表已经连上数据库；需要探活时再显式调用 PingContext。正常使用结束后调用 db.Close()，不要把关闭动作交给 Connector。

五、Driver.Open 与 DriverContext 的兼容边界

driver.Driver 的旧接口仍要求实现 Open(name string)。实现 DriverContext 时通常保留它，用于兼容只会调用 Open 的旧路径；但两条路径应共享同一个建连函数，避免 DSN 解析、认证参数或资源释放规则出现两份不一致的代码。

func (d driverImpl) Open(name string) (driver.Conn, error) {
	// 旧接口没有 ctx，只能使用 Background；不应伪造一个可取消的请求上下文。
	return openConn(context.Background(), name)
}

func (d driverImpl) OpenConnector(name string) (driver.Connector, error) {
	// 新路径先复用同一套 DSN 校验，再把配置交给 Connector。
	if strings.TrimSpace(name) == "" {
		return nil, errors.New("empty DSN")
	}
	return connectorImpl{dsn: name}, nil
}

兼容实现有三个边界：第一，Open 无法接收调用方的取消信号；第二，OpenConnector 返回错误时不应泄漏已经创建的资源；第三，Connector 的 Connect 可能被并发调用，保存的 DSN 和其他配置必须是只读或并发安全的。

排查清单

常见追问

OpenConnector 的 name 一定是完整 DSN 吗？

它是传给驱动的连接名，通常由驱动约定为 DSN。解析规则属于驱动，不是 database/sql 统一规定的格式。

Connect(ctx) 成功后还能继续使用 ctx 吗？

可以用它完成当前建连，但不要把这个请求上下文当作连接的永久生命周期。查询、事务等操作应按各自接口接收新的上下文。

只实现 Driver.Open 能不能工作？

可以，旧接口仍可工作；只是驱动无法通过 Connector.Connect(ctx) 获得连接创建阶段的上下文。需要这项能力时再补充 DriverContext。

小结

实现 DriverContext 时，把职责固定成“OpenConnector 保存并校验 DSN，Connector.Connect(ctx) 创建一次连接，Connector.Driver() 返回所属 Driver”。保留 Driver.Open 作为兼容入口，并让两条路径共享底层建连逻辑，就能在不破坏旧调用方的前提下，把取消和超时传递到新连接的创建阶段。