在 Python 数据库开发中，SQLAlchemy 是使用最广泛的 ORM 框架之一。许多开发者习惯于通过 engine.execute() 直接执行原生 SQL 语句，但在处理 MERGE（也常称为 UPSERT）语句时，却频繁遭遇异常或静默失败。这个问题在 Stack Overflow、GitHub Issues 以及技术社区中引发了大量讨论。本文将从底层实现角度，解析这一现象的原因，并给出替代方案。
一、MERGE 语句的特殊性
MERGE 语句是 SQL 标准中用于“存在则更新，不存在则插入”的原子化操作，在 Oracle、PostgreSQL、SQL Server 中均有对应实现（如 PostgreSQL 的 ON CONFLICT 子句，SQL Server 的 MERGE 关键字）。与传统 INSERT 或 UPDATE 不同，MERGE 通常需要一次执行中完成条件判断、行锁、多表操作，因此其执行路径与普通 DML 语句存在差异。
在 SQLAlchemy 的 Engine 对象中，execute() 方法本质上是调用 Connection.execute()，而该方法默认使用 exec_driver_sql 进行编译和执行。对于大多数 SELECT、INSERT、UPDATE、DELETE 语句，这种直接执行方式没有问题。但 MERGE 语句在不同数据库中具有不同的语法风格和参数绑定机制，SQLAlchemy 的 exec_driver_sql 无法统一处理这些差异。
二、根本原因：参数绑定与编译差异
具体来说，engine.execute() 在执行时会尝试将 Python 参数转换为 SQL 参数占位符（如 %s 或 ?）。然而，许多数据库的 MERGE 语句中，参数可能同时出现在 WHEN MATCHED 和 WHEN NOT MATCHED 子句中，甚至需要引用同一个参数多次。例如，PostgreSQL 的 ON CONFLICT DO UPDATE SET column = EXCLUDED.column 要求参数必须与 UPDATE 子句中的列名严格对应。如果使用 engine.execute("MERGE ...", params)，SQLAlchemy 的默认参数处理器会将参数视为普通位置参数，导致绑定顺序错乱，最终引发 InterfaceError 或 ProgrammingError。
以 PostgreSQL 为例，常见错误代码如 psycopg2.errors.SyntaxError: argument of WHEN NOT MATCHED must be a boolean，实际上是参数绑定失败导致的。类似地，在 SQL Server 中，MERGE 语句的 OUTPUT 子句也会与默认执行器产生冲突。
三、安全替代方案
针对这一问题，社区与官方均推荐以下方法：
-
使用
text()构造显式文本：通过from sqlalchemy import text将 SQL 字符串包装为TextClause对象。text()允许明确指定参数绑定模式（如:param命名参数），并支持数据库方言的自动转义。例如：
python stmt = text("MERGE INTO target t USING source s ON t.id = s.id WHEN MATCHED THEN UPDATE SET t.val = :val ...") with engine.connect() as conn: conn.execute(stmt, {"val": 123}) -
直接使用原始数据库连接：如果项目未深度依赖 SQLAlchemy 的 ORM 功能，可以获取原始 DB-API 连接（通过
engine.raw_connection()），然后调用该数据库驱动的标准cursor.execute()。这种方式完全绕过了 SQLAlchemy 的参数处理，但需要自行管理连接生命周期。 -
使用 ORM 的
upsert方法（SQLAlchemy 2.0+）：新版本中，insert()语句支持on_conflict_do_update等后缀，这是官方推荐的面向 SQLAlchemy Core 的方式。它不仅能正确生成跨库的MERGE语句，还能自动处理参数绑定。
四、专家建议与社区共识
SQLAlchemy 核心维护者 Mike Bayer 曾多次在邮件列表中强调：“engine.execute() 是一个便利方法，设计初衷是用于简单、标准的 SQL 操作。当遇到 MERGE、INSERT...ON DUPLICATE KEY UPDATE 等方言特有语法时，开发者应改用 Connection.execute() 与 text() 的组合，或者直接使用 Core 的 insert().on_conflict_do_update()。” 他还指出，许多用户遇到的“执行无报错但数据未更新”的问题，往往是因为 MERGE 语句本身语法错误被静默忽略（某些驱动将非致命错误转化为警告）。
五、总结：理解抽象层边界
engine.execute() 不适用于 MERGE 语句，本质上是 SQLAlchemy 抽象层与数据库方言差异之间的天然矛盾。对于从事数据工程或 ETL 开发的团队，建议建立以下规范：
- 所有包含条件逻辑的复杂 DML（MERGE、UPSERT、REPLACE）优先使用
text()显式声明； - 在测试环境中使用
echo=True参数开启 SQL 日志，观察实际发往数据库的语句是否正确； - 定期关注 SQLAlchemy 更新日志，因为 2.0 版本大幅增强了参数绑定的一致性。
只有理解了工具的设计边界，才能写出既优雅又健壮的数据库代码。技术无捷径，深入底层思维才是解决疑难杂症的正道。