Python sqlite3 命名占位符为什么不能传序列

我把一段旧的 SQLite 查询从较早的 Python 环境迁到 Python 3.14 时，最先遇到的不是 SQL 语法错误，而是参数容器不对：SQL 写的是 :name，调用却传了一个 tuple。现在这类写法不能再靠“刚好按顺序对应”来侥幸运行，命名占位符应当配字典。

看到 :name、:year 这样的命名占位符，就把参数写成包含同名键的 dict；只有 ? 这类 qmark 占位符才使用 tuple 或其他序列。Python 3.14 起，命名占位符传序列会明确抛出 ProgrammingError。

一、先看清命名占位符的参数契约

这次迁移里最容易误判的地方，是把“参数是可迭代对象”理解成“list、tuple、dict 都可以”。实际规则取决于 SQL 中占位符的写法：

官方文档还特别说明，命名风格的字典必须包含所有命名参数，多余键会被忽略；qmark 风格的序列长度则必须和占位符数量一致。这样一来，下面两种写法的意图是清楚的：

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()

# 命名占位符按键名绑定，不要把 tuple 当成 dict 使用
cur.execute("SELECT :name AS name, :year AS year", {
    "name": "Python",
    "year": 1991,
})

# qmark 占位符按位置绑定，序列长度要与问号数量一致
cur.execute("SELECT ? AS name, ? AS year", ("Python", 1991))

con.close()  # 示例结束后主动关闭连接

二、为什么升级后才暴露这个问题

Python 3.14 的 sqlite3.Cursor.execute() 和 executemany() 都明确规定：使用命名占位符时，参数或每一项参数必须是 dict，传 sequence 会产生 ProgrammingError。这不是 SQLite 把字段名改了，而是 Python 适配层把原本容易误解的调用边界说清楚了。

因此，旧代码即使在升级前没有立刻失败，也不值得继续依赖。序列没有字段名，SQL 一旦调整占位符顺序，调用方就可能“能运行但绑错值”；字典则把数据和字段直接对应起来。迁移时我会先搜索 :xxx 与 execute(..., (...))、executemany(..., rows) 同时出现的地方，再逐个看参数结构。

三、把单条和批量写入一起改掉

单条查询只需把第二个参数改成 dict。批量写入则不是把外层 list 换成 dict，而是让“每一行”都是 dict，外层仍然是可迭代对象：

import sqlite3

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE user(name TEXT, age INTEGER)")

# 单条 DML 使用一个 dict，键名对应 SQL 中的命名占位符
con.execute(
    "INSERT INTO user(name, age) VALUES(:name, :age)",
    {"name": "Lin", "age": 28},
)

rows = [
    {"name": "Ming", "age": 31},
    {"name": "Jia", "age": 26},
]
# 批量写入要求每一项都是 dict，而不是 tuple
con.executemany(
    "INSERT INTO user(name, age) VALUES(:name, :age)",
    rows,
)
con.commit()  # 写入后提交事务，避免关闭连接时丢失改动

count = con.execute("SELECT COUNT(*) FROM user").fetchone()[0]
print(count)  # 结果示意：3
con.close()

这里的 age 只是示例字段。真正迁移时，字典键应与 SQL 占位符逐一对应；不要为了“兼容旧代码”把字典的 values() 转回 tuple，那会重新丢掉命名绑定的优势。

四、上线前用一张清单收口

• 搜索所有 :[字段名] 占位符，确认调用参数是 dict。
• 检查每个 dict 是否覆盖全部命名参数；多余键虽然会被忽略，但最好清理以免误导维护者。
• 检查 executemany() 的每一项，而不是只检查外层容器。
• 如果想传 tuple，就把 SQL 改成全部使用 ?，并核对顺序和数量。
• 补一个最小回归用例：正常绑定、缺键、qmark 长度不匹配，以及 Python 3.14 下命名占位符传序列。

对我来说，这次改动的价值不只是让新版本通过，而是把 SQL 字段和 Python 数据结构的契约写在代码里。升级完成后，优先看异常类型和失败调用位置，不要先去改 SQLite 表结构。

相关问题

命名占位符可以传 list 吗？

不应这样写。命名占位符使用 dict；Python 3.14 起传 sequence 会抛出 ProgrammingError。

字典里多一个键会失败吗？

官方规则允许多余项被忽略，但生产代码最好删除无关键，避免字段改名时留下误导。

什么时候适合用 tuple？

SQL 明确使用 ? qmark 占位符、参数数量少且位置关系稳定时可以用 tuple；字段较多或经常调整时，命名占位符配 dict 更直观。

参考资料：Python 官方 sqlite3 文档：https://docs.python.org/3/library/sqlite3.html。