SQLAlchemy实现“存在则更新，不存在则插入”优雅写法

在 SQLAlchemy 中实现“存在则更新、不存在则插入”（upsert）并非只有笨拙的手动查询+判断一条路——本文系统梳理了五种高效优雅的方案：针对 PostgreSQL 的 `on_conflict_do_update`、MySQL 的 `on_duplicate_key_update`、SQLite 的 `prefix_with("OR REPLACE")`，通用 ORM 层的 `merge()` 方法，以及兼顾兼容性与控制力的手动 `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、统一提交事务以保证原子性。

今天关于《SQLAlchemy实现“存在则更新，不存在则插入”优雅写法》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！