SQLAlchemy2.0+使用位置参数执行原生SQL方法

亲爱的编程学习爱好者，如果你点开了这篇文章，说明你对《SQLAlchemy 2.0+ 使用位置参数执行原生 SQL 方法》很感兴趣。本篇文章就来给大家详细解析一下，主要介绍一下，希望所有认真读完的童鞋们，都有实质性的提高。

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）等驱动级占位符及位置元组：

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 + 位置参数的官方、高效、事务安全的标准方案。

本篇关于《SQLAlchemy2.0+使用位置参数执行原生SQL方法》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！