PostgreSQL用ON CONFLICT、MySQL用ON DUPLICATE KEY UPDATE实现原子upsert；SQLAlchemy需按方言分别调用on_conflict_do_update()或on_duplicate_key_update()，不可混用；merge()非原子操作，高并发下有竞态风险。
PostgreSQL 用 ON CONFLICT 实现 upsert
PostgreSQL 原生支持 INSERT ... ON CONFLICT，这是最直接、最高效的方式。SQLAlchemy 1.4+ 提供了 insert().on_conflict_do_update() 接口，但仅对 PostgreSQL 生效。
关键点：必须明确指定冲突目标（如主键或唯一索引列），否则会报 ON CONFLICT clause does not specify any conflict targets 错误。
-
index_elements参数填主键或唯一约束字段名（如['id']或['email']） -
set_里写更新逻辑，值可用excluded.column_name引用插入行的原始值 - 若表无显式命名唯一约束，不能用
index_name，只能靠index_elements
from sqlalchemy.dialects.postgresql import insertstmt = insert(User).values(id=1, name='Alice', email='a@example.com') stmt = stmt.on_conflict_do_update( indexelements=['id'], # 冲突检测列 set={'name': stmt.excluded.name, 'email': stmt.excluded.email} ) session.execute(stmt) session.commit()
MySQL 用 ON DUPLICATE KEY UPDATE 替代
MySQL 没有 ON CONFLICT，对应的是 INSERT ... ON DUPLICATE KEY UPDATE。SQLAlchemy 不提供跨方言的统一 upsert API，所以得手动适配。
常见错误：直接复用 PostgreSQL 的 on_conflict_do_update() 会导致 AttributeError（该方法在 MySQL dialect 中不存在）。
- 检查
engine.dialect.name，区分 PostgreSQL / MySQL 分支处理 - MySQL 下用
insert(...).on_duplicate_key_update()（需 SQLAlchemy 1.4+ + pymysql/mariadb driver） -
on_duplicate_key_update的参数是字典，键为列名，值可为字面量或text()表达式
from sqlalchemy.dialects.mysql import insert as mysql_insertif engine.dialect.name == 'mysql': stmt = mysql_insert(User).values(id=1, name='Alice', email='a@example.com') stmt = stmt.on_duplicate_key_update( name=stmt.inserted.name, email=stmt.inserted.email ) else:
PostgreSQL 分支（同上）
stmt = insert(User).values(...) stmt = stmt.on_conflict_do_update(...)兼容写法：用原生 SQL +
text()绕过方言限制如果项目必须用单一代码路径覆盖多数据库，且不想写 if 分支，可退回到原生 SQL 字符串 +
text()，由开发者保证语法正确性。风险在于失去 ORM 层的类型转换和参数绑定安全，容易引入 SQL 注入或类型错位（比如把字符串当 int 绑定）。
- PostgreSQL：
INSERT INTO user (id, name) VALUES (:id, :name) ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name - MySQL：
INSERT INTO user (id, name) VALUES (:id, :name) ON DUPLICATE KEY UPDATE name = VALUES(name) - 所有参数必须用
:param占位符，再传入session.execute(text(...), {'id': 1, 'name': 'Alice'})
注意：MySQL 的 VALUES(column) 是特殊函数，不是字面值；PostgreSQL 的 EXCLUDED 是关键字，大小写敏感。
为什么不能依赖 merge()？
session.merge() 看似能“自动 upsert”，但它不是原子操作：先 SELECT 判断存在性，再决定 INSERT 或 UPDATE。在高并发下可能产生竞态（两个事务同时查不到记录，然后都插入，触发唯一约束错误）。
-
merge()还会触发完整对象加载和属性比对，性能差于原生命令 - 它不规避数据库层的约束冲突，仍可能抛出
IntegrityError - MySQL 和 PostgreSQL 对
merge()的行为一致，但底层仍是两步，无法替代真正的 upsert
真正需要 upsert 的场景（如日志去重、计数器更新、缓存同步），必须用数据库原生的原子插入/更新语义，而不是 ORM 的模拟逻辑。
