Python sqlite3 怎样绑定动态查询参数

当筛选条件来自表单、接口或配置文件时，sqlite3 的正确做法是把“值”交给参数绑定，把“SQL 结构”留在受控代码里。不要用 f-string、% 或字符串拼接把输入直接塞进查询。Python 官方文档把这种机制称为 parameter substitution：问号占位符接收序列，命名占位符接收字典。

官方地址：https://docs.python.org/3/library/sqlite3.html

先把动态值和 SQL 结构分开

一个查询通常同时包含两类动态内容：用户填写的值，以及程序选择的字段、排序方式或条件分支。前一类适合绑定，后一类属于 SQL 语法，必须由代码中的固定映射或白名单决定。

import sqlite3

def find_orders(con, customer_id, state):
    # SQL 结构保持固定，用户输入只作为两个值传给占位符。
    sql = """
        SELECT id, state, total
        FROM orders
        WHERE customer_id = ? AND state = ?
        ORDER BY id DESC
    """
    # 元组顺序必须与 SQL 中两个问号的出现顺序一致。
    return con.execute(sql, (customer_id, state)).fetchall()

这里的 customer_id 和 state 不会改变 SQL 的语法结构。数据库驱动负责把它们作为值处理，输入中即使包含引号，也不会被当成查询片段。写入操作同样使用这套方式，提交事务仍由调用方按业务边界决定。

qmark 和 named 怎样绑定查询值

qmark 风格适合条件数量固定、参数顺序清晰的查询。SQL 中有几个 ?，参数序列就要提供几个值，少一个或多一个都会破坏对应关系。

# qmark：用序列按位置绑定值
sql = "SELECT id, name FROM users WHERE state = ? AND level >= ?"
params = ("active", 3)
# 参数数量与两个问号一一对应，避免把输入拼进 SQL 文本。
rows = con.execute(sql, params).fetchall()

named 风格适合筛选条件较多、希望按字段语义阅读的场景。占位符写成 :state、:min_level，第二个参数传字典；字典可以多出暂时不用的键，但不能缺少 SQL 中需要的键。

# named：用字典按名称绑定值
sql = """
    SELECT id, name
    FROM users
    WHERE state = :state AND level >= :min_level
"""
params = {"state": "active", "min_level": 3}
# 键名和占位符对应，阅读查询时不必依赖参数位置。
rows = con.execute(sql, params).fetchall()

批量写入可以把同一个 SQL 和多组参数交给 executemany()。需要注意的是，命名占位符的每一项也应是字典；不要把位置序列和命名占位符混用。若占位符和参数容器不匹配，sqlite3 会抛出 ProgrammingError，这通常比悄悄拼出错误 SQL 更容易定位。

动态 IN 条件要先生成占位符

最容易踩坑的是“筛选 ID 列表”。下面的写法不能工作：WHERE id IN (?) 再把整个列表作为一个参数传入，因为一个占位符只代表一个值，不会自动展开成多个 SQL 参数。

def find_by_ids(con, ids):
    # 空列表没有自然的 IN 语义，先由业务决定返回空结果还是跳过查询。
    if not ids:
        return []

    # 占位符数量由输入集合长度决定，但每个具体 ID 仍然走参数绑定。
    placeholders = ", ".join("?" for _ in ids)
    sql = f"SELECT id, name FROM users WHERE id IN ({placeholders})"
    return con.execute(sql, tuple(ids)).fetchall()

这里的 f-string 只生成由程序控制的问号和逗号，不承载任何用户值。真正的 ID 仍在第二个参数中传入。空集合不能机械地生成 IN ()：有的业务应该直接返回空列表，有的业务可能把“没有筛选”解释为不加条件，必须先明确语义。

表名和排序方向为什么不能直接绑定

参数绑定面向“值”，不能把表名、列名或 ASC/DESC 这类语法片段当成值传入。例如 ORDER BY ? 通常只会把参数当作一个常量表达式，而不是列名。安全做法是把外部选项映射到固定 SQL 片段。

# 只允许映射表中出现的列名和排序关键字，避免外部输入成为 SQL 结构。
SORT_COLUMNS = {"newest": "created_at", "price": "total"}
SORT_DIRECTIONS = {"up": "ASC", "down": "DESC"}

column = SORT_COLUMNS.get(sort_key, "created_at")
direction = SORT_DIRECTIONS.get(direction_key, "DESC")
sql = f"SELECT id, total FROM orders ORDER BY {column} {direction} LIMIT ?"
# LIMIT 的数值仍然是普通值，继续通过占位符绑定。
rows = con.execute(sql, (limit,)).fetchall()

映射表里的字符串由程序维护，和直接接收任意输入拼接不是一回事。若列名来自数据库元数据或多租户配置，也要先转换为应用认可的固定集合，再放进 SQL。

落地时检查这四个边界

最后再确认连接和事务边界：查询结果取完后关闭游标或连接，写操作在合适的位置提交；不要为了“参数安全”忽略连接生命周期。参数绑定解决的是值进入 SQL 的方式，不能替代权限控制、输入业务校验和查询超时策略。

常见问题

qmark 和 named 应该选哪一个？

条件少且顺序稳定时用 qmark；条件较多或需要按名称阅读时用 named。一个查询里尽量保持一种风格，减少维护时的对应错误。

能不能把字段名作为参数传给 execute？

不能按普通值绑定。字段名和排序关键字属于 SQL 结构，应从固定映射中选择；真正的数值或文本值继续使用占位符。