Go database/sql 怎么用命名参数适配不同驱动

在 Go 项目里把查询条件写成 sql.Named("user_id", id)，并不等于所有数据库都能直接执行 :user_id。database/sql 负责承接带名称的参数，真正怎样识别占位符、是否支持命名参数，仍由驱动决定。要适配不同驱动，最稳妥的做法是把“业务参数名称”和“SQL 占位符语法”分开管理。

sql.Named 适合保留参数语义、减少参数顺序误读；它不是通用 SQL 重写器。MySQL 常见写法仍是 ?，PostgreSQL 常见写法是 $1、$2，原生 pgx 则可以使用自己的 NamedArgs 能力。

命名参数解决的是哪一层问题

sql.Named 的价值首先是表达意图。与其把 id、status、limit 按位置塞进参数列表，不如让调用点保留字段名，后续增加条件时不容易把顺序配错。标准库把它包装成 NamedArg，再交给驱动检查和转换。

但 SQL 文本如何写仍是另一件事。数据库服务器识别的是驱动最终发送的语句，database/sql 不会凭空把所有 :name、@name 都改写成当前数据库能接受的语法。于是“参数有名字”和“SQL 支持命名占位符”必须分别确认。

用 sql.Named 保留业务字段名

在能接受命名参数的接口或驱动场景中，可以先把参数边界写清楚。下面的示例把两个条件显式命名，并使用上下文和延迟关闭连接；实际 SQL 占位符仍要以目标驱动文档为准。

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

query := `SELECT id, email FROM users WHERE tenant_id = :tenant_id AND state = :state`
args := []any{
	sql.Named("tenant_id", tenantID), // 保留租户条件的业务名称
	sql.Named("state", "active"),    // 保留状态条件的业务名称
}

rows, err := db.QueryContext(ctx, query, args...)
if err != nil {
	return fmt.Errorf("query active users: %w", err) // 包装错误，保留调用上下文
}
defer rows.Close() // 读取多行结果后释放结果集

这段代码表达了参数语义，但不能据此断言 MySQL、PostgreSQL 都能原样执行。若驱动只接受位置占位符，就应让 SQL 使用它支持的形式，同时仍可保留 sql.Named 作为代码侧的语义标记；如果驱动把名称当作不支持的参数特性，调用会在执行阶段报错，这时要改的是适配策略，而不是继续堆叠同名参数。

按驱动改写占位符

跨数据库项目通常有一条清晰边界：上层仓储方法用 tenantID、state 这样的业务名，下层方言负责把它们排成驱动所需的 SQL 和参数。MySQL 驱动常用问号占位符，PostgreSQL 常用编号占位符；二者都不应靠字符串替换随意处理引号和注释。

// 方言层只负责占位符和参数顺序，不拼接用户输入。
func activeUsersQuery(dialect string) (string, []any, error) {
	switch dialect {
	case "mysql":
		return `SELECT id, email FROM users WHERE tenant_id = ? AND state = ?`,
			[]any{tenantID, "active"}, nil // 顺序与两个 ? 一一对应
	case "postgres":
		return `SELECT id, email FROM users WHERE tenant_id = $1 AND state = $2`,
			[]any{tenantID, "active"}, nil // 编号占位符仍按参数位置绑定
	default:
		return "", nil, fmt.Errorf("unsupported dialect: %s", dialect) // 明确拒绝未知方言
	}
}

如果项目只使用 PostgreSQL，可以直接评估 pgx 原生接口的 NamedArgs；如果必须兼容 database/sql 生态，则要把 stdlib 适配器的能力单独验证。不要把某个驱动的扩展能力写进所有驱动都能复用的公共接口。

按项目约束选择适配策略

工具选型可以按三个问题判断：是否只连接一种数据库，是否已有大量 database/sql 依赖，是否需要把同一套仓储代码迁移到另一种方言。单库、重视 PostgreSQL 专属能力时，原生 pgx 的表达力更完整；多库或依赖 ORM、通用扫描库时，保留 database/sql，并把占位符方言隔离在仓储层更稳。

重复出现的字段名也要谨慎。某些命名参数实现允许同名占位符复用，另一些实现会按位置展开；如果公共层无法证明驱动行为一致，宁可显式传两个参数，或者在方言层把重复引用展开成两个位置参数。

常见问题

sql.Named 会自动把 :id 改成 ? 吗？

不会。它只创建带名称和值的 NamedArg；占位符解析或改写是驱动、扩展库或方言层的职责。

使用 ? 还能传入 sql.Named 吗？

不能把它当成跨驱动保证。若目标驱动按位置消费参数，直接传基础值通常更清晰；若要保留名称，应先确认驱动是否实现了相应的命名参数检查。

为什么 PostgreSQL 示例常见 $1 而不是 :name？

PostgreSQL 的常见参数协议是编号占位符。命名体验可以由 pgx 原生 NamedArgs 或其他查询构造层提供，但这不是 PostgreSQL 服务器对所有客户端的统一语法。

把命名语义和方言语法分开

最终可以记住一句话：sql.Named 让 Go 参数更容易读，驱动方言决定 SQL 怎样写。公共层保存业务字段名，适配层负责占位符、顺序和重复参数，发布前再用目标驱动的最小查询确认支持范围。这样换数据库时，变的是方言模块，不是每个业务调用点。