PG10升级到PG16时，如何安全迁移自定义函数与扩展？

Question

在将 PostgreSQL 10 升级至 16 的过程中，一个常见且高危的技术问题是：**自定义函数（尤其是用 PL/pgSQL、PL/Python 或 C 编写的函数）及第三方扩展（如 pg_stat_statements、postgis、pg_trgm）因接口变更、弃用语法或底层 API 不兼容而 silently 失效或行为异常**。例如，PG12 废弃了 `pg_get_ruledef()` 中的旧参数签名，PG14 移除了 `CREATE AGGREGATE ... SFUNC` 中的隐式类型转换支持，PG15 调整了 `jsonb` 函数的空值处理逻辑；而 PostGIS 3.0+ 要求 PG12+，无法直接在 PG10 dump 中恢复。若仅依赖 `pg_dump --clean --if-exists` 迁移，未提前验证函数体兼容性、未重编译 C 扩展、未检查 `pg_available_extensions` 版本匹配，极易导致应用调用时崩溃、静默截断或统计指标丢失。如何系统识别、测试并安全重构这些“隐形依赖”，是升级成败的关键瓶颈。

Answer 1

```html

一、现象识别：从“静默失效”到“行为漂移”的典型征兆

升级后应用无报错但结果异常（如地理围栏计算偏移、JSONB聚合丢失null键、统计视图返回空集），日志中无ERROR但WARNING频发（WARNING: function ... is not available in this version），pg_stat_statements 查询耗时突增或calls=0——这些是隐形依赖崩塌的早期信号。需警惕PG10→16跨越6个主版本带来的语义断层累积效应。

二、根因解构：三类兼容性断裂面深度剖析

类型	PG版本关键变更点	典型失效案例
PL/pgSQL语法层	PG12废弃pg_get_ruledef(oid, boolean)；PG14禁用隐式类型转换在CREATE AGGREGATE	自定义规则函数返回NULL而非空字符串；聚合函数因输入类型不匹配返回ERROR: function does not exist
扩展ABI层	PostGIS 3.0+要求PG12+ ABI；pg_trgm 1.6+重构show_trgm()返回结构	PG10 dump恢复PostGIS 3.3时CREATE EXTENSION postgis直接失败；全文检索相似度计算结果偏差>40%
C扩展API层	PG13重写内存上下文管理；PG15废弃MemoryContextAlloc()旧签名	自研C函数在高并发下触发core dump；pg_stat_statements v1.9在PG16中无法收集执行计划

三、系统化识别：四维扫描法构建兼容性知识图谱

1. 静态解析层：用pg_dump -s --no-owner --no-privileges导出DDL，配合pg_upgrade --check + 自研pg_compat_scanner工具扫描CREATE FUNCTION中的弃用函数调用（如pg_get_expr()旧参数）
2. 动态探针层：在PG16测试实例中启用log_min_error_statement = warning，捕获运行时WARNING: deprecated function usage
3. 扩展拓扑层：查询SELECT name, default_version, installed_version FROM pg_available_extensions，比对https://pgxn.org/各扩展的PG版本支持矩阵
4. 行为验证层：对每个自定义函数生成test_case.json（含边界值、null、超长字符串），在PG10/PG16双环境执行并diff输出

四、安全重构：渐进式迁移的五阶段流水线

graph LR A[PG10生产库] --> B[静态兼容性扫描] B --> C{是否含C扩展？} C -->|是| D[源码级重编译
适配PG16头文件] C -->|否| E[PL/pgSQL函数体语法修正] D --> F[扩展安装验证
pg_available_extensions检查] E --> F F --> G[影子流量回放
应用请求双写PG10/PG16] G --> H[差异分析报告
自动标记行为漂移函数] H --> I[灰度发布
按schema分批切换]

五、实战验证：PostGIS与jsonb空值处理的修复范例

问题：PG15+中jsonb_set('{"a":1}'::jsonb, '{b}', 'null'::jsonb)返回{"a":1,"b":null}（PG10为{"a":1}）。修复方案：

-- 兼容性包装函数（PG10/PG16均可运行）
CREATE OR REPLACE FUNCTION safe_jsonb_set(
  target jsonb, 
  path text[], 
  new_value jsonb,
  create_missing boolean DEFAULT true
) RETURNS jsonb AS $$
BEGIN
  IF current_setting('server_version_num')::int >= 150000 THEN
    RETURN jsonb_set(target, path, new_value, create_missing);
  ELSE
    -- PG10兼容逻辑：显式处理null值
    RETURN CASE 
      WHEN new_value IS NULL THEN target #- path
      ELSE jsonb_set(target, path, new_value, create_missing)
    END;
  END IF;
END;
$$ LANGUAGE plpgsql;

六、长效治理：构建升级韧性基础设施

• 将pg_upgradecheck集成至CI/CD流水线，每次扩展升级前自动触发
• 建立企业级pg_compatibility_registry表，记录每个函数/扩展的PG版本支持区间
• 为所有C扩展启用PG_MODULE_MAGIC校验，在加载时强制验证ABI版本
• 在应用层注入pg_version_check()健康检查端点，实时暴露版本不匹配风险

```