PostgreSQL 9.5：INSERT ON CONFLICT（UPSERT）源码级深度解析与9.5→18演进

北漂老男孩

614人浏览 · 2026-01-12 23:30:00

北漂老男孩 · 2026-01-12 23:30:00 发布

PostgreSQL 9.5：INSERT ON CONFLICT（UPSERT）源码级深度解析与9.5→18演进

本文围绕 PostgreSQL 9.5 引入的 INSERT ON CONFLICT（UPSERT）特性，提供从语法与行为到源码路径的系统性认知，并概览后续版本的相关演进。内容包括：概述、背景、名词解释、源码映射、并发与WAL关系、性能与配置、兼容性与迁移、Mermaid 流程图（配色与样式优化）、参考资料与“速记口”总结。

简介与项目背景

在 9.5 之前，应用通常通过 SELECT/UPDATE/INSERT 组合或函数封装实现“存在则更新、不存在则插入”的逻辑，存在竞态窗口与复杂锁处理。9.5 原生支持 UPSERT，将唯一约束/索引冲突检测与冲突后的动作（DO NOTHING/DO UPDATE）纳入 INSERT 语句一次性完成，显著简化业务代码并提升一致性。

该特性依赖唯一约束/索引作为仲裁对象（arbiter），并在执行器中实现冲突路径分支；语法层新增 ON CONFLICT 关键字与 EXCLUDED 伪表以引用待插入的行值。

名词解释

UPSERT：当插入遇到唯一约束/索引冲突时，转而更新（或忽略）冲突行的语义。
ON CONFLICT：INSERT 的子句，用于声明冲突目标与冲突处理策略。
EXCLUDED：UPSERT 中的伪表，代表拟插入但被排除（excluded）的行值，可用于更新表达式。
冲突目标（Conflict Target）：列列表或约束名，指明用来判断冲突的唯一索引/约束。
DO NOTHING / DO UPDATE：冲突时的两种处理动作。

源码映射与实现要点

语法解析与语义：

语法扩展定义与解析位于：src/backend/parser/gram.y
目标列与 EXCLUDED 引用的分析与重写相关逻辑位于：src/backend/parser/

执行器与冲突路径：

修改/插入执行路径在：src/backend/executor/nodeModifyTable.c
插入与唯一冲突检测依赖 B-Tree 索引的插入过程与检查，核心代码在：src/backend/access/nbtree/nbtinsert.c
Heap 层插入/更新相关实现位于：src/backend/access/heap/heapam.c

元数据与约束：

唯一约束/索引的定义与查找涉及系统目录与约束机制，参考：src/backend/catalog/

WAL 与压缩（与 9.5 同期的相关架构改动）：

9.5 新增 WAL 页压缩（PGLZ），代码位于：src/common/pg_lzcompress.c
新增 WAL 记录头结构，参考：src/include/access/xlogrecord.h

说明：本文以文件路径级别标注源码位置，具体函数调用链可在上述文件中进一步检索以获得实现细节。

语法与行为详解

语法要点：
- INSERT INTO … ON CONFLICT (conflict_column_list) DO NOTHING
- INSERT INTO … ON CONFLICT (conflict_column_list) DO UPDATE SET … = EXCLUDED…
- INSERT INTO … ON CONFLICT ON CONSTRAINT constraint_name DO UPDATE …
EXCLUDED 用法：在 DO UPDATE 子句中引用拟插入行的列值，如 EXCLUDED.col。
冲突目标：必须可映射到一个唯一约束或唯一索引；否则会报错。

示例 SQL（更多示例文件）：sql/insert_on_conflict_examples.sql

行为语义（简化）：

正常插入路径：未触发冲突 → 直接写入。
冲突路径：
- DO NOTHING：忽略本次插入，不报错。
- DO UPDATE：基于冲突行进行更新，更新表达式可引用 EXCLUDED。
隔离级别与并发：在高并发下，B-Tree 唯一约束/索引仲裁确保一致性；必要时会进行重试或锁竞争处理。

并发控制与 WAL 关系

并发控制：唯一索引插入过程在 B-Tree 层进行冲突检测与必要的锁控制，相关实现参考：src/backend/access/nbtree/nbtinsert.c
WAL 写入：UPSERT 的插入/更新路径都会产生日志；9.5 的 Full Page Write 在首次更新后可能触发，结合 wal_compression 可降低 I/O；压缩实现参考：src/common/pg_lzcompress.c
检查点与恢复：WAL 新格式及相关恢复路径见：src/include/access/xlogrecord.h

性能与配置

配置项：
- wal_compression：是否对 FPI（Full Page Images）压缩（9.5 新增，默认 off），源码参考：src/common/pg_lzcompress.c
- 相关唯一索引设计：合理选择冲突目标的唯一索引列，避免宽索引与热点冲突。
性能建议：
- 批量 UPSERT 时，可根据业务热点分布进行分片/分区以降低冲突概率。
- 合理使用 DO NOTHING 与 DO UPDATE，降低不必要的写放大。
简要对比：9.5 引入原生 UPSERT 后，相较于 9.4 的“手工实现”，在高并发、冲突率较高的场景下显著减少应用侧逻辑与锁争用复杂度；后续版本（如 12 的 B-Tree 改进、14 的 dedup）间接改善写入/冲突行为的整体性能。

兼容性与迁移

从 9.4 及更早版本迁移：将自定义的 upsert 函数/存储过程替换为原生 INSERT ON CONFLICT；校验所有更新表达式是否正确引用 EXCLUDED。
约束与索引：确保冲突目标能准确指向唯一约束或唯一索引；必要时创建或调整索引。
触发器与规则：评估现有触发器在 DO UPDATE 路径上的副作用与顺序。

Mermaid 流程图（配色与样式优化）

下图给出 UPSERT 决策流程。为缓解视觉疲劳，采用柔和配色与边框样式，并对关键路径加深颜色：

从 9.5 到 18 的相关演进概览（与 UPSERT 关联的方向）

9.5：原生 UPSERT 与 WAL 压缩引入；系统目录与执行器配套改造。
9.6：并行查询等增强（与 UPSERT间接相关性有限）。
10：声明式分区（UPSERT 在分区表的行为需结合分区键与唯一约束设计）。
11：大量性能与语法改进（与 UPSERT 直接改动有限）。
12：B-Tree 改进（如更好的页面管理），在高冲突写入场景下可受益。
13~14：索引层 dedup/优化，进一步提升写入局部性与空间效率。
15~18：更多执行器与存储层稳健性增强，UPSERT 作为成熟特性保持稳定。

注：上列为与 UPSERT 最相关的宏观方向性梳理，详尽版本特性请参考各版本新特性文档与 Release Notes。

参考资料与权威链接

PostgreSQL 9.5 Release Notes（官方）：https://www.postgresql.org/docs/9.5/release-9-5.html
INSERT 文档（官方）：https://www.postgresql.org/docs/current/sql-insert.html
ON CONFLICT 语法（官方）：https://www.postgresql.org/docs/current/sql-insert.html#SQL-ON-CONFLICT
WAL 压缩实现参考：src/common/pg_lzcompress.c
WAL 记录头结构：src/include/access/xlogrecord.h
执行器插入修改路径：src/backend/executor/nodeModifyTable.c
B-Tree 唯一冲突检测与插入：src/backend/access/nbtree/nbtinsert.c
Heap 层插入/更新：src/backend/access/heap/heapam.c

速记口（面试/设计复盘快速记忆）

关键词：UPSERT、ON CONFLICT、EXCLUDED、唯一约束/索引、DO NOTHING、DO UPDATE。
语法骨架：INSERT … ON CONFLICT (idx_cols|ON CONSTRAINT name) DO {NOTHING|UPDATE SET col=EXCLUDED.col,…}
源码定位：解析src/backend/parser/gram.y → 执行src/backend/executor/nodeModifyTable.c → 索引插入/检测src/backend/access/nbtree/nbtinsert.c → Heap 写入src/backend/access/heap/heapam.c
并发与一致性：唯一索引仲裁；更新路径引用 EXCLUDED；必要锁与重试避免竞态。
配置联动：wal_compression 可降低 FPI 压力（9.5 引入），但默认 off。
迁移提示：替换旧有自研 upsert 流程；确保唯一索引正确；评估触发器副作用。