sqlite3 named parameter 怎样绑定命名参数

在 Python 的 sqlite3 中，命名参数的关键是：SQL 使用 :参数名 占位，第二个参数传入一个以同名字符串为键的字典，字典键不写冒号。这样 SQL 结构和值彼此分开，查询条件多时也比位置参数更容易核对。

官方文档：https://docs.python.org/3/library/sqlite3.html

最小可用写法是 con.execute("... WHERE username = :username", {"username": value})。占位符名和字典键必须对应；缺少必需键会失败，多出的键不会参与绑定。

sqlite3 named parameter 的写法是什么

先把值留在 SQL 之外。下面的例子使用内存数据库，只展示绑定关系；实际项目把连接路径替换成自己的数据库文件即可。

import sqlite3

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE users (id INTEGER, username TEXT, enabled INTEGER)")
con.executemany(
    "INSERT INTO users VALUES (:id, :username, :enabled)",
    [
        {"id": 1, "username": "lina", "enabled": 1},
        {"id": 2, "username": "mori", "enabled": 0},
    ],
)

sql = "SELECT id, username FROM users WHERE username = :username AND enabled = :enabled"
params = {"username": "lina", "enabled": 1}
row = con.execute(sql, params).fetchone()
print(row)

# 关闭连接，示例结束后释放数据库资源
con.close()

注意两处细节：SQL 中的 :username 带冒号，字典中的 "username" 不带；execute() 的第二个参数直接传字典，不要再把字典包成单元素元组。查询条件和值的对应关系可以从 params 一眼看出。

executemany 怎样绑定多行命名参数

批量写入时，SQL 只写一份，第二个参数改成由多个字典组成的可迭代对象。每个字典都应提供当前 SQL 需要的键，字段顺序不再依赖列表位置。

records = [
    {"id": 3, "username": "qing", "enabled": 1},
    {"id": 4, "username": "yu", "enabled": 1},
]

# 每个字典代表一行，键名对应 SQL 中的命名占位符
con.executemany(
    "INSERT INTO users (id, username, enabled) VALUES (:id, :username, :enabled)",
    records,
)
con.commit()  # 写入文件数据库时显式提交事务

for record in con.execute(
    "SELECT id, username FROM users WHERE enabled = :enabled",
    {"enabled": 1},
):
    print(record)

批量参数适合来自表单清洗结果或业务对象转换后的字典。若某一行漏掉 enabled，不要用空字符串“补齐”来掩盖问题，应在进入数据库层前整理好数据结构，并保留异常上下文。

缺少键、额外键和 NULL 条件怎么排查

命名绑定的错误通常集中在键名和 SQL 条件，而不是 SQLite 语法本身。

例如可空条件不要把运算符和字段名一起交给参数绑定：

nickname = None
if nickname is None:
    sql = "SELECT id FROM users WHERE username IS NULL"
    params = {}
else:
    sql = "SELECT id FROM users WHERE username = :username"
    params = {"username": nickname}

# SQL 结构由程序选择，用户值仍然通过参数绑定
rows = con.execute(sql, params).fetchall()

参数绑定负责值，不负责列名、表名、排序关键字或运算符。需要动态选择这些 SQL 结构时，先使用程序内部的白名单映射，再把实际值作为命名参数传入；不要用字符串拼接承载用户输入。

常见问题

字典的键要不要写冒号？

不要。SQL 写 :username，字典写 {"username": "lina"}。

named parameter 能替代所有 SQL 拼接吗？

它适合绑定值，不会自动替换表名、列名和排序方向；这些结构应由白名单选择。

为什么批量写入推荐字典？

每一行通过字段名表达意图，列顺序变化时不容易把值错绑到相邻字段。

总结一下：固定 SQL 结构、用 :name 留出值的位置、用不带冒号的字典键传值；批量操作使用字典迭代器；遇到异常先查缺失键和 NULL 语义，再检查是否把动态 SQL 结构误当成了可绑定值。