sqlalchemy 2.0+ 已移除对 `execute()` 方法直接传入位置参数元组的支持，但可通过 `exec_driver_sql()` 方法安全、高效地使用 `(%s, %s)` 等驱动级占位符配合元组传参，且兼容事务上下文。
在 SQLAlchemy 2.0 及更高版本中，session.execute() 和 connection.execute() *不再接受解包的位置参数元组（如 `values`）或裸元组**，这是为统一参数绑定模型、增强安全性与可维护性而做的关键变更。当你尝试如下写法时：
query = "INSERT INTO test VALUES (%s, %s, %s)" values = (1, 2, 3) session.execute(text(query), values) # ❌ ArgumentError: List argument must consist only of tuples or dictionaries
会触发 sqlalchemy.exc.ArgumentError —— 因为 execute() 此时仅接受命名参数字典（如 {"a": 1, "b": 2}）或批量操作的元组列表（如 [(1,2,3), (4,5,6)]），不支持单个位置元组。
✅ 正确解法：使用 exec_driver_sql()
该方法专为“直通数据库驱动”场景设计，行为完全类比 DB-API 的 cursor.execute(sql, params)，原生支持 %s（MySQL/PyMySQL）、?（SQLite）等驱动级占位符及位置元组：
SkillSub Pro - Python 题解与代码注释双功能技能功能概述SkillSub Pro - Python 题解与代码注释双功能技能是一项面向实际任务的技能，主要用于SkillSub Pro 是一个 Python 题解生成与代码注释的 双功能合体技能 ，专为学生、算法学习者和开发者设计；✅ 一个技能，两种用途 ：；核心要点📝 题解模式 ：输入题目/题号，自动生成完整 Python 题解（含详细注释、解题思路、复杂度分析）；💬 注释模式 ：输入 Python 代码，自动添加详细中。它将相关步骤、
from sqlalchemy import text
# ✅ 推荐：使用 connection.exec_driver_sql()
with engine.connect() as conn:
conn.exec_driver_sql("INSERT INTO test VALUES (%s, %s, %s)", (1, 2, 3))
conn.commit() # 若非自动提交模式需显式提交
# ✅ 在 Session 中使用（保持同一事务连接）
with Session(engine) as session:
# 所有 ORM 操作与原生 SQL 共享同一连接和事务
session.execute(text("UPDATE users SET active = :v WHERE id = :id"), {"v": True, "id": 100})
# 使用 exec_driver_sql 执行位置参数 SQL
session.connection().exec_driver_sql(
"INSERT INTO logs (user_id, action, ts) VALUES (%s, %s, NOW())",
(100, "login")
)
session.commit()
⚠️ 注意事项：
- exec_driver_sql() 不解析 SQL，不支持 text() 对象，必须传入纯字符串；
- 占位符必须严格匹配底层驱动（MySQL 用 %s，PostgreSQL 用 %s 或 %(name)s，SQLite 用 ?）；
- 在 Session 中调用 session.connection().exec_driver_sql() 是安全的，它复用当前事务连接，不会破坏隔离级别或导致隐式提交；
- 避免混用 execute(text(...)) 与 exec_driver_sql() 处理同一逻辑——建议对复杂动态 SQL 统一采用 exec_driver_sql() + 位置元组，对 ORM 风格查询继续使用 text() + 命名参数。
? 小技巧：若需动态构建大量字段插入语句，可结合 Python 字符串格式化生成占位符：
fields = ["id", "name", "email", "created_at"]
placeholders = ", ".join(["%s"] * len(fields))
query = f"INSERT INTO users ({', '.join(fields)}) VALUES ({placeholders})"
session.connection().exec_driver_sql(query, (1, "Alice", "a@b.com", "2024-01-01"))
总之，放弃 *values 解包幻想，拥抱 exec_driver_sql() —— 它是 SQLAlchemy 2.0+ 中处理长 SQL + 位置参数的官方、高效、事务安全的标准方案。
