Go database/sql.NamedArg 为什么有些驱动不能按名字绑定参数

我第一次把一条位置参数 SQL 换成命名参数时，代码看起来更清楚了，结果换到另一套数据库驱动后却报错。后来才发现，sql.Named 负责携带名称和值，但它不负责把 SQL 里的占位符翻译成另一种写法；能不能按名字绑定，最终由驱动的占位符语法和接口支持决定。

NamedArg 不是通用的 SQL 占位符转换器。驱动能够识别 driver.NamedValue.Name，并且 SQL 中使用了它支持的命名占位符时，按名字绑定才成立；否则就应改用该驱动支持的位置参数，仍然保留参数化查询。

官方资料：https://pkg.go.dev/database/sql#NamedArg

先看懂 NamedArg 实际交给了谁

sql.Named("user_id", 42) 产生的是一个带有 Name 和 Value 的 sql.NamedArg。调用 ExecContext 或 QueryContext 后，database/sql 会把它整理成驱动层的 driver.NamedValue。这一步保存了名称，但没有替你修改 SQL 文本。

package main

import (
	"context"
	"database/sql"
)

func renameUser(ctx context.Context, db *sql.DB, userID int64, name string) error {
	// @name 和 @user_id 是否可用，由当前驱动和数据库的占位符语法决定。
	_, err := db.ExecContext(ctx,
		"UPDATE users SET display_name = @name WHERE id = @user_id",
		sql.Named("name", name),   // 名称不带 @ 前缀，值交给 database/sql 转换。
		sql.Named("user_id", userID), // 这里的名称要和 SQL 占位符语义对应。
	)
	return err
}

还有一个容易忽略的细节：官方文档要求 Name 不带占位符前缀。也就是说，代码传 sql.Named("user_id", 42)，而不是把 @、: 或 $ 一起放进名称里。前缀属于 SQL 和驱动的语法，不属于 NamedArg.Name。

为什么换一个驱动，按名字就可能失效

驱动支持命名参数，不只是看 SQL 里有没有一个看起来像名字的占位符。database/sql/driver 提供了 NamedValueChecker 接口，让连接或语句在参数送入驱动前检查、转换并处理名称。官方文档给出的检查顺序是：语句级 Stmt.NamedValueChecker、连接级 Conn.NamedValueChecker、语句级 ColumnConverter，最后才是 DefaultParameterConverter。

如果驱动没有走能够保留名称的接口，而是落到旧的只接收 []driver.Value 的调用路径，带有名称的参数就没有地方可表达。Go 源码中的转换逻辑会在这种路径遇到非空名称时返回“不支持命名参数”的错误。因此，问题不在 NamedArg 本身，而在驱动能否接住 driver.NamedValue 以及它是否认识对应的占位符。

这也解释了为什么同一段 Go 代码在一个驱动上可用，在另一个驱动上会报错：驱动可能使用 ?、$1、:name 或其他语法；即使驱动实现了命名参数，也未必接受你写的那种占位符。

遇到兼容性问题时，先分三层判断

我现在排查这类问题，会把“绑定失败”拆成三个独立问题，而不是马上把 NamedArg 换成字符串拼接。

1. SQL 层：确认数据库和驱动规定的占位符形状。@name、:name 和 $1 不是 database/sql 的统一标准。
2. 驱动接口层：确认驱动是否支持带名称的 driver.NamedValue，以及调用的是上下文接口还是旧式接口。
3. 参数层：确认传入的名称没有前缀，名称和 SQL 中的命名占位符能对应，普通值也能被默认参数转换器转换。

如果错误信息明确提到驱动不支持 Named Parameters，优先检查第二层；如果错误更像 SQL 语法错误，优先检查第一层。两者都正常但自定义类型转换失败时，再看 driver.Valuer 或驱动自己的检查逻辑。

不支持命名参数时，改用位置参数仍然安全

当驱动只支持位置占位符时，最稳妥的改法是把 SQL 写成它支持的形式，同时按同样顺序传值。不要为了保留字段名而把用户输入拼进 SQL。

func renameUserPositional(ctx context.Context, db *sql.DB, userID int64, name string) error {
	// 使用驱动支持的位置占位符，参数仍由 database/sql 单独传递。
	_, err := db.ExecContext(ctx,
		"UPDATE users SET display_name = ? WHERE id = ?",
		name,   // 第一个 ? 对应 display_name。
		userID, // 第二个 ? 对应 id，顺序不能错位。
	)
	return err
}

位置参数的缺点是 SQL 较长时可读性不如命名参数，但它并不等于不安全。真正需要避免的是把值直接拼到 SQL 字符串中；占位符和参数列表分离，仍然是参数化查询。

NamedValueChecker 不是“让所有驱动自动支持命名”的开关

如果你正在编写数据库驱动，或需要理解某个驱动的自定义类型处理，可以把 NamedValueChecker 看成驱动接收参数的扩展点。它能识别特殊类型、转换值，也能在必要时返回 driver.ErrSkip，把当前参数交回后续的列转换器或默认转换器。

type checker struct{}

func (checker) CheckNamedValue(nv *driver.NamedValue) error {
	// 驱动可以在这里识别自定义值或检查 Name；普通值交给默认路径。
	if _, ok := nv.Value.(customValue); ok {
		// 这里应返回驱动可接受的底层值，而不是把任意对象直接传下去。
		return nil
	}
	return driver.ErrSkip // 表示继续走后续转换检查，不代表 SQL 执行成功。
}

driver.ErrRemoveArgument 是另一种特殊语义：它表示当前参数不进入最终的查询参数列表，适合驱动定义查询选项时使用。它不是“忽略名称”的替代品，普通业务参数不应随意返回它。

最后用这张表决定写法

所以，NamedArg 能否按名字绑定，不是 Go 代码单方面决定的能力。先确认驱动的占位符和参数接口，再在命名参数与位置参数之间做选择；无论选哪种，参数都应继续作为独立参数传递。

相关问题

NamedArg 的 Name 要不要写 @ 或冒号？

不要写。Name 应只保留名称本身，前缀由 SQL 占位符语法表达。

位置参数是不是就不能防 SQL 注入？

不是。只要值仍作为独立参数传给 Exec 或 Query，位置参数同样属于参数化查询。

实现了 NamedValueChecker 就一定能使用任意命名占位符吗？

不一定。检查器解决的是驱动如何接收和转换参数，SQL 占位符的词法和数据库语法仍由具体驱动与数据库决定。