SQLAlchemy实现upsert有五种方式：一、PostgreSQL用on_conflict_do_update；二、通用ORM用merge()；三、MySQL用on_duplicate_key_update；四、SQLite用prefix_with("OR REPLACE")；五、跨库兼容用SELECT+INSERT/UPDATE。
如果您在使用 SQLAlchemy 时需要实现“存在则更新，不存在则插入”的逻辑，即通常所说的 upsert 操作，但又希望避免重复查询或手动判断主键/唯一约束冲突，则需依赖数据库原生支持与 SQLAlchemy 的适配机制。以下是几种不同数据库后端下的具体实现方式：
一、使用 on_conflict_do_update（PostgreSQL）
PostgreSQL 提供了 INSERT ... ON CONFLICT DO UPDATE 语法，SQLAlchemy 通过 on_conflict_do_update 方法直接封装该能力，需指定冲突目标（如唯一索引列）和更新字段。
1、确保模型已定义 __table_args__ 中包含 UniqueConstraint 或主键。
2、构造 insert 语句并调用 on_conflict_do_update，传入 index_elements 参数指定冲突列。
3、在 set_ 方法中传入字典，声明冲突时要更新的字段及值，例如 {"name": excluded.name, "updated_at": func.now()}。
二、使用 merge（通用 ORM 方式）
SQLAlchemy 的 merge() 方法基于主键或标识符查找对象：若 session 中已存在相同主键的对象，则同步属性；若不存在，则添加新实例。该方法不依赖数据库层 upsert 语法，但要求模型定义明确主键且数据一致性由应用层保障。
1、创建目标模型实例，并设置其 主键字段（如 id）或 唯一标识字段（如 name）。
2、调用 session.merge(instance)，此时 SQLAlchemy 自动执行 SELECT + INSERT/UPDATE 判断逻辑。
3、执行 session.commit() 完成持久化。
三、使用 insert().on_duplicate_key_update（MySQL）
MySQL 支持 INSERT ... ON DUPLICATE KEY UPDATE，SQLAlchemy 通过 on_duplicate_key_update 扩展实现，需确保表上存在 PRIMARY KEY 或 UNIQUE 约束。
1、使用 insert(Model) 构造语句。
2、链式调用 on_duplicate_key_update，传入关键字参数形式的更新字段映射，例如 name=inserted.name, updated_at=func.now()。
3、执行 session.execute(stmt) 并提交事务。
四、使用 SQLite 的 INSERT OR REPLACE
SQLite 不支持标准 upsert 语法，但提供 INSERT OR REPLACE 行为：当违反 PRIMARY KEY 或 UNIQUE 约束时，自动删除旧行并插入新行。SQLAlchemy 可通过 prefix_with("OR REPLACE") 实现等效效果。
1、构造标准 insert 语句：insert(Model).values(...)。
2、添加前缀 prefix_with("OR REPLACE")，使生成 SQL 为 INSERT OR REPLACE INTO ...。
3、注意该方式会触发 DELETE + INSERT，可能影响外键级联或自增 ID 连续性。
五、手动执行 SELECT + INSERT/UPDATE（跨库兼容方案）
当目标数据库不支持原生 upsert 或需精细控制冲突逻辑时，可显式分离查询与写入步骤。此方式完全可控，但引入额外 round-trip 开销与竞态风险，建议配合 SELECT FOR UPDATE 或事务隔离级别提升安全性。
1、使用 session.query(Model).filter(...).with_for_update() 查询是否存在匹配记录。
2、根据查询结果调用 session.add() 或 session.query().update()。
3、统一提交事务以保证原子性。
