psycopg3 不允许在单个 execute() 调用中执行多条 SQL 命令（如分号分隔的多个 DELETE），需拆分为独立语句依次执行；本文介绍正确做法、替代方案及关键注意事项。
psycopg3 不允许在单个 `execute()` 调用中执行多条 sql 命令（如分号分隔的多个 delete），需拆分为独立语句依次执行；本文介绍正确做法、替代方案及关键注意事项。
在使用 psycopg3（尤其是与 SQLAlchemy Core 配合）时，一个常见误区是将多条 SQL 语句拼接为一个字符串（如用分号连接两个 DELETE），然后试图通过一次 cursor.execute() 执行。这会触发 psycopg.errors.SyntaxError: cannot insert multiple commands into a prepared statement 错误——因为 psycopg3 的参数化查询严格禁止多语句执行（这是出于安全考虑，防止 SQL 注入和语义歧义）。
✅ 正确做法：拆分为独立语句，分别执行
from sqlalchemy import text
identifiers = ['id100', 'id200']
sql_statements = [
"DELETE FROM related_table WHERE entity_id IN (SELECT f.id FROM main_table f WHERE identifier IN %(ids)s);",
"DELETE FROM main_table WHERE identifier IN %(ids)s;"
]
params = {'ids': identifiers} # 复用同一参数名，提升一致性与可维护性
conn = self.db_engine.raw_connection()
try:
cursor = conn.cursor()
for stmt in sql_statements:
cursor.execute(text(stmt), params)
conn.commit() # 显式提交事务
except Exception:
conn.rollback()
raise
finally:
cursor.close()
conn.close()
? 关键优化说明：
- 使用统一参数名 %(ids)s 替代 %(id1)s/%(id2)s，避免冗余定义，且 PostgreSQL 支持数组参数直接用于 IN 子句（需确保 identifiers 是非空列表）；
- 必须显式管理事务：多语句逻辑本质是原子性操作，应包裹在 try/except/finally 中，确保出错时回滚，成功后提交；
- 避免手动拼接 SQL 字符串（如 f"DELETE ... {identifiers}"），始终使用参数化查询防止注入。
? 更优替代方案（推荐）： 若业务允许，优先使用 数据库级外键约束 + ON DELETE CASCADE，让 PostgreSQL 自动处理关联删除，既高效又原子：
-- 执行一次即可（需在建表或 ALTER 时设置） ALTER TABLE related_table ADD CONSTRAINT fk_entity_id FOREIGN KEY (entity_id) REFERENCES main_table(id) ON DELETE CASCADE;
此后只需一条语句：
cursor.execute(text("DELETE FROM main_table WHERE identifier IN %(ids)s;"), {'ids': identifiers})
⚠️ 注意事项：
- psycopg3 不支持 executemany() 执行 DDL/DML 多语句组合；
- 即使使用 cursor.executescript()（psycopg2 特有），psycopg3 也已移除该方法；
- 若需更高性能且数据量极大，可考虑 INSERT INTO ... SELECT + TRUNCATE 或批量 UNLOGGED 临时表中转，但需权衡事务安全与复杂度。
综上，多语句删除应以“拆分 + 事务封装”为标准实践，而非绕过驱动限制；长期来看，合理设计外键级联策略才是健壮、简洁的解决方案。
