当前位置：首页 > 文章列表 > 文章 > python教程 > Python sqlite3 命名占位符为什么不能传序列

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

来源：17golang原创 2026-09-12 13:11:32 0浏览收藏

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

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

要点速览

命名占位符看字段名绑定，参数必须是 dict。
qmark 占位符看位置绑定，参数序列长度必须匹配。
升级时同时检查 execute() 和 executemany()，不要只修单条查询。

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

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

SQL 写法	参数容器	匹配方式
`WHERE name = :name`	`dict`	按键名绑定
`WHERE name = ?`	序列	按出现顺序绑定

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

Python sqlite3 命名占位符与 dict、qmark 占位符与序列的参数对应示意图 — 图1：命名占位符与 dict、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，外层仍然是可迭代对象：

Python sqlite3 execute 与 executemany 使用字典绑定后的参数映射和结果状态示意图 — 图2：execute 与 executemany 统一使用字典绑定后的结果关系示意图。

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，那会重新丢掉命名绑定的优势。