read_sql的params参数必须显式传入，不可字符串拼接；支持问号占位符（SQLite/MySQL/PostgreSQL）或命名参数（SQL Server需text()包裹）；IN查询需动态生成占位符；datetime等类型须用原生实例避免隐式转换错误。
read_sql 的 params 参数必须显式传入，不能靠字符串拼接
很多人以为用 f"SELECT * FROM users WHERE id = {user_id}" 就能动态查，结果遇上 user_id = "1 OR 1=1" 直接被拖库。Pandas 的 read_sql 和 read_sql_query 原生支持参数化查询，但必须通过 params 参数透传，底层由 SQLAlchemy 或 DB-API 驱动完成转义和类型绑定。
错误写法：pd.read_sql(f"SELECT * FROM t WHERE id = {uid}", engine) —— 不仅危险，还可能因类型不匹配报 sqlite3.InterfaceError 或 psycopg2.DataError。
- SQLite/PostgreSQL/MySQL 均支持问号占位符：
"SELECT * FROM t WHERE status = ? AND created_at > ?"，params传元组，如(“active”, “2024-01-01”) - SQL Server 或需命名参数时，用
text()包裹 SQL，并写:param_name，再配params={"param_name": value} - 参数值为
None时，会自动映射为 SQL 的NULL，无需手动处理空值逻辑
不同数据库驱动对 params 的语法要求不一致
不是所有驱动都兼容同一种占位符。SQLite 和 psycopg2 默认认问号（?），而 SQL Server + pyodbc 必须用命名参数（:name 或 @name），且需配合 text() 使用，否则 params 被忽略。
典型失败场景：pd.read_sql("SELECT * FROM t WHERE id = :id", engine, params={"id": 123}) 在 SQLite 上直接报 sqlite3.OperationalError: near ":id": syntax error —— 因为 SQLite 不解析冒号语法。
立即学习“Python免费学习笔记（深入）”；
- SQLite / MySQL（pymysql）：用
?占位，params是元组或列表 - PostgreSQL（psycopg2）：支持
%s（位置）和%(name)s（命名），但read_sql统一推荐用?+ 元组，避免驱动差异 - SQL Server（pyodbc）：必须用
text()+:name，且连接 URL 中要带odbc_connect字段
WHERE 条件含列表 or 多值 IN 查询怎么写
IN 子句不能直接把 Python 列表塞进 params，否则会被当单个对象传入，导致 WHERE id IN (?) 匹配失败。得动态生成等长占位符串，再展开列表为参数。
例如查 [101, 205, 312]，不能写 params=([101, 205, 312],)，而要：
- 构造 SQL：
f"SELECT * FROM orders WHERE id IN ({','.join(['?'] * len(ids))})" - 传参：
params=tuple(ids) - 注意：SQLite 有最大变量数限制（通常 999），超量需分批或改用临时表
datetime 或特殊类型字段传参容易类型错配
Python 的 datetime.date、datetime.datetime 大多能被驱动自动转换，但 numpy.datetime64 或字符串格式（如 "2025-03-15"）常被当普通文本传入，导致索引失效或比较出错。
常见症状：WHERE created_at >= "2025-03-15" 返回空，但数据库里明明有数据——其实是字符串字典序比较，不是日期比较。
- 强制统一用
datetime.date或datetime.datetime实例，别传字符串 - 若来源是 Pandas Series，先调
.dt.date或.dt.to_pydatetime()转原生类型 - PostgreSQL 用户注意：
timestamp with time zone字段传参时，params值最好带tzinfo，否则可能被按本地时区解释
真正卡住人的往往不是语法，而是参数类型在 Python、Pandas、驱动、数据库四层之间悄悄变形。检查 params 里的每个值，用 type(x) 看一眼，比反复重试 SQL 更快定位问题。
