pg_json_diff

概览

Source requires PostgreSQL 12+ and C++17. Packaging removes the unsupported control-file author field; no extension dependency.

版本

构建

您可以使用 pig build 命令构建 pg_json_diff 扩展的 RPM / DEB 包：

pig build pkg pg_json_diff         # 构建 RPM / DEB 包

安装

您可以直接安装 pg_json_diff 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

pig install pg_json_diff;          # 当前活跃 PG 版本安装

pig ext install -y pg_json_diff -v 18  # PG 18
pig ext install -y pg_json_diff -v 17  # PG 17
pig ext install -y pg_json_diff -v 16  # PG 16
pig ext install -y pg_json_diff -v 15  # PG 15
pig ext install -y pg_json_diff -v 14  # PG 14

dnf install -y pg_json_diff_18       # PG 18
dnf install -y pg_json_diff_17       # PG 17
dnf install -y pg_json_diff_16       # PG 16
dnf install -y pg_json_diff_15       # PG 15
dnf install -y pg_json_diff_14       # PG 14

apt install -y postgresql-18-pg-json-diff   # PG 18
apt install -y postgresql-17-pg-json-diff   # PG 17
apt install -y postgresql-16-pg-json-diff   # PG 16
apt install -y postgresql-15-pg-json-diff   # PG 15
apt install -y postgresql-14-pg-json-diff   # PG 14

创建扩展：

CREATE EXTENSION pg_json_diff;

用法

来源：

• 官方 README
• 扩展 SQL
• C++ 实现

pg_json_diff 1.0 提供三个基于 nlohmann/json 的不可变 JSONB 转换函数：生成 RFC 6902 JSON Patch、应用这种补丁，或应用 RFC 7386 合并补丁。它适合明确的文档转换，不是自动冲突解决器，也不是稳定的审计差异格式。

核心流程

先生成补丁，保存或检查它，再验证应用补丁后是否得到预期目标：

CREATE EXTENSION pg_json_diff;

WITH docs AS (
  SELECT '{"name":"Ada","age":30}'::jsonb AS old_doc,
         '{"name":"Ada","age":31,"city":"London"}'::jsonb AS new_doc
), patch AS (
  SELECT old_doc, new_doc, generate_json_diff(old_doc, new_doc) AS operations
  FROM docs
)
SELECT operations, apply_patch(old_doc, operations) = new_doc AS verified
FROM patch;

应用外部提供的补丁前应先验证，并在事务及应用级授权保护下执行转换。

函数索引

• generate_json_diff(source, target) 返回 RFC 6902 操作数组。
• apply_patch(document, patch) 支持添加、删除、替换、移动、复制与测试操作。
• merge_patch(document, patch) 递归合并对象；空值成员删除键，数组则整体替换而不是合并。

三个函数都接受并返回 jsonb。

运维说明

每次调用都会把 PostgreSQL JSONB 序列化为文本，解析成 C++ JSON 值，执行操作，再次序列化并重新解析为 JSONB。因此，大型或深层嵌套文档会产生复制与解析开销。nlohmann/json 与 PostgreSQL JSONB 的数值模型不同，应测试超大整数和高精度小数的保真度。补丁错误会以通用内部错误返回；生成的操作顺序与路径也不应当作规范化的人类审计记录。