谁该看这篇：维护 PostgreSQL 14 自建实例的 DBA，需要盘点扩展并验证升级前置条件。
后端工程师，需要确认应用实际调用的扩展功能在目标版本仍可用。
SaaS 技术负责人，需要判断团队能否在支持截止前完成演练并安排切换。
最后更新于 2026 年 10 月 28 日；数据核实自 PostgreSQL 官方版本支持页、14 系列发布说明及目标版本文档。 官方于 2026 年 8 月发布的 14.24 更新公告再次确认了停止接收修复的日期。(PostgreSQL 14.24 发布公告)
PostgreSQL 14 扩展兼容检查：查清“装了什么”与“实际依赖什么”
升级前不要只记住某个数据库里 \dx 显示的结果。扩展是按数据库安装的，同一集群中的不同数据库可能各自启用了不同扩展；而数据库对象、部署脚本或应用代码还可能依赖没有被你第一眼想到的函数、类型、运算符、索引操作符类或外部共享库。
先连接到每个数据库，分别导出当前已安装扩展及版本：
SELECT current_database() AS database_name,
e.extname,
e.extversion,
n.nspname AS extension_schema
FROM pg_extension AS e
JOIN pg_namespace AS n ON n.oid = e.extnamespace
ORDER BY e.extname;
pg_extension 记录当前数据库已安装的扩展及其版本；它不是整个集群或应用依赖的完整清单。(PostgreSQL 的 pg_extension 系统目录说明) 再检查当前服务器安装目录能提供哪些扩展版本：
SELECT name, default_version, installed_version
FROM pg_available_extensions
ORDER BY name;
怎样确认 PostgreSQL 14 实例里实际安装了哪些扩展？ 对每个数据库分别查询 pg_extension，把数据库名、扩展名和版本保存到迁移记录；再把结果与应用代码、迁移脚本、数据库部署脚本、定时任务和运维文档交叉核对。pg_available_extensions 显示的是当前这套服务器环境可用的扩展，不等于应用真正调用了哪些功能。(PostgreSQL 的 pg_available_extensions 视图说明)
实务上至少要区分三类信息：
- 已经安装：
pg_extension中存在记录；记录了数据库当前登记的扩展版本。 - 环境可提供：
pg_available_extensions或pg_available_extension_versions列出目标实例可用的版本；这仍不能证明应用功能通过测试。 - 应用实际依赖：SQL、ORM、存储过程、索引定义、迁移脚本和任务中引用的扩展对象。仅靠系统视图无法完整推断这一层，必须结合代码与业务路径查找。
如果多个数据库、应用服务和部署仓库分属不同团队，尽早请各负责人确认清单。漏掉一个冷门数据库里的扩展，往往会让正式切换期间才出现的缺失依赖变成回退难题。
扩展同名但目标文件缺失：先核对安装环境与更新路径
如何判断扩展能否用于新的 PostgreSQL 主版本？ 不能只凭扩展名称判断。目标服务器需要安装与目标 PostgreSQL 主版本匹配的扩展文件；扩展本身还需要能在该目标版本运行。扩展文件可能包含 .control 控制文件、SQL 安装或升级脚本，以及供服务器加载的共享库。(PostgreSQL 扩展机制文档)
在隔离的目标版本实例上，先检查可用扩展和版本，再逐一对照现网记录。一个常见误区是：目标环境能查到同名扩展，就推断现有版本可以直接升级。实际上，当前数据库登记的扩展版本，可能没有到目标环境所提供版本的更新脚本路径。官方扩展机制要求存在适当的更新脚本，ALTER EXTENSION UPDATE 才能按路径更新扩展定义。(PostgreSQL ALTER EXTENSION 命令说明)
在目标环境里，针对每个扩展检查已知更新路径：
SELECT *
FROM pg_extension_update_paths('扩展名');
记录当前已安装版本、目标环境的可用版本，以及两者之间是否存在非空更新路径。这个结果帮助你发现缺少更新脚本等问题，但不代替阅读扩展发布方针对目标 PostgreSQL 版本的兼容说明，也不代替应用测试。目标环境的操作系统、软件包来源和安装方式同样会影响扩展文件能否实际加载。
大版本升级后，扩展版本是否还需另行处理？ 视扩展而定：有些扩展需要准备目标大版本对应的文件，有些还需要在数据库升级后执行扩展更新；是否有适用路径，要看扩展自身提供的文件和脚本。不要把“数据库集群升级成功”理解成“扩展已经更新”。将每个扩展标为“目标文件已确认”“更新路径已确认”“需扩展发布方进一步确认”或“未通过”，未确认项应先隔离复现。
pg_upgrade 检查通过，不等于应用扩展功能通过
用 pg_upgrade 预检时，怎样定位扩展相关的兼容阻塞？ 先在与生产配置尽量一致的目标环境安装 PostgreSQL 新版本及所需扩展文件，再运行 pg_upgrade --check。官方说明指出，可用 --check 先执行兼容性检查；大版本升级还需要目标环境中的扩展共享库与新服务器二进制匹配。(PostgreSQL pg_upgrade 文档)
实际调用参数取决于你的安装目录、数据目录和升级工具位置，以下仅展示结构，不可直接照抄路径：
pg_upgrade \
--old-bindir=/path/to/old/bin \
--new-bindir=/path/to/new/bin \
--old-datadir=/path/to/old/data \
--new-datadir=/path/to/new/data \
--check
按失败类型排查，而不是把所有报错都归结为“扩展不兼容”：
- 目标环境没有扩展文件：确认目标版本对应的软件包或构建产物是否安装；检查控制文件、SQL 脚本及必要的共享库是否存在。不要从旧版本目录直接复制二进制文件后就视为兼容。
- 扩展版本没有更新路径：检查当前扩展版本和目标环境提供的版本；向扩展发布方核实是否需要先在旧 PostgreSQL 环境更新扩展，或是否必须采用其他迁移方式。先在隔离环境验证，不要在生产库上尝试未经演练的升级脚本。
- 扩展对象或依赖导致失败：检查扩展创建的类型、函数、索引、操作符及应用对象依赖。删除或卸载前要确认业务没有使用这些对象，并在测试库中验证清理的影响。
- 预检查成功但应用失败：检查连接驱动、ORM、迁移工具及应用调用的 SQL。
pg_upgrade --check关注的是升级工具能够检查的集群兼容条件，不是端到端业务验收。
出现错误后，保留完整命令、标准输出和错误日志，并标注目标 PostgreSQL 版本与扩展安装来源。官方升级说明应作为工具行为依据；具体扩展的兼容结论仍要回到该扩展的官方文档或发布说明，不能用某个社区案例推断所有使用者。(PostgreSQL 18 pg_upgrade 文档)
扩展能安装但业务报错：用真实调用路径做隔离验证
扩展安装成功，只能说明安装流程至少走通了，不能证明应用在目标版本上仍能正确使用扩展功能。测试范围应从依赖清单中抽取：应用实际调用的函数、关键查询、扩展提供的类型与运算符、依赖扩展的索引，以及执行结果和错误处理。
建议按照以下步骤形成可复核的验收记录：
- 完整盘点：逐个数据库导出已安装扩展、版本与 schema；结合代码仓库、迁移脚本、定时任务和运维任务补齐应用依赖。
- 准备目标环境：安装计划采用的 PostgreSQL 大版本及对应扩展文件，记录操作系统、安装来源、扩展版本和配置；不要把生产目录当作试验场。
- 检查更新路径：核对目标环境可用扩展版本与
pg_extension_update_paths()的结果；对缺失文件、空路径或不明确的兼容说明设置阻塞标记。 - 执行升级预检查：按实际数据目录、二进制目录和计划使用的模式运行
pg_upgrade --check，保存日志并按错误类型逐项处理。预检查没有替代应用测试。 - 验证应用功能：在隔离环境运行关键查询、函数调用、索引相关查询和迁移脚本；检查 ORM、连接驱动、备份恢复工具能否与目标版本配合。
- 演练恢复与回退：确认备份来自机外，并实际恢复到隔离环境；写清切换失败时如何停止应用写入、保留旧集群并恢复服务。数据库升级方式会影响回滚条件，不能只准备一条“切回旧版本”的口头方案。
- 评审并决定切换：由 DBA、应用负责人和运维负责人共同签字确认扩展清单、验证结果、备份恢复结果、切换步骤与回退条件；未解决的阻塞项必须明确负责人和处理时限。
扩展测试结果应包含扩展名及版本、目标 PostgreSQL 版本、安装来源、操作步骤、预期结果、实际现象、日志位置和回退办法。没有自己执行测试，就只记录测试方法，不写“已兼容”“升级成功”或性能提升等结论。
未完成验证时暂缓生产切换：按条件决定继续还是回退
按下面的条件分支作决定，而不是只看日历：
- 若每个数据库的扩展清单已核实、目标环境有匹配文件、需要的更新路径已确认，且隔离环境中的关键应用功能测试与备份恢复演练通过，则进入生产切换评审。
- 若扩展文件缺失，但扩展发布方提供了明确的目标版本支持方案，则先在隔离环境安装并复现完整测试；测试未通过前保持生产方案不变。
- 若更新路径为空、扩展兼容状态不明，或业务功能失败，则将其视为阻塞项；评估替代扩展、应用改造或其他迁移方式，并重新演练，不能把风险留到生产切换窗口处理。
- 若备份无法恢复、回退条件不清，或关键应用负责人尚未验收，则暂缓切换。停止支持日期是规划边界，不是跳过验证的理由。
扩展迁移只是大版本升级准备的一部分，本文不替你选择目标 PostgreSQL 版本，也不提供通用迁移执行方案。准备实施前，可继续阅读本站的服务器内存与磁盘规划说明，把数据库、日志、临时文件和备份的容量需求分开评估；同时将SSH 接入方式说明纳入目标环境操作准备。
自建目标环境核对：资源与数据保护分开决策
如果你打算把数据库部署到独享物理服务器，先根据实际工作负载核对内存、磁盘和系统环境，而不是把硬件规格直接当作升级兼容证明。OSFP Cloud 提供 AMD EPYC 7543P 独享物理机，内存有 128GB 和 256GB 两档 DDR4-3200 ECC RDIMM；默认有 2 块 1TB 直连 NVMe，可选增加 NVMe 磁盘。具体可用方案应以OSFP Cloud 产品信息为准。
这里有几项容易影响决策的边界：
- 内存：按数据库工作集、连接数、操作系统和同机进程评估，不要仅凭标称容量判断缓冲区是否合适。
- 磁盘：直连 NVMe 便于你自行规划数据目录与日志布局，但本站没有硬件 RAID；需要冗余时，应自行规划软件 RAID 或复制，并另做机外备份。
- 系统与接入：确认目标系统版本能够安装你要用的 PostgreSQL 与扩展；Linux 服务器通过 SSH 接入。系统可安装情况及具体硬件选项以产品信息为准。
- 备份与责任：独享硬件不等于自动冗余，也不等于数据库托管或迁移服务。安装、扩展兼容验证、备份恢复和生产切换仍需由你的团队负责。
如果你当前使用托管数据库，常见取舍是扩展安装权限受平台支持范围约束、底层资源与磁盘布局可调空间有限、账单可能包含独立计算或存储项目；如果使用共享云主机，还需检查资源是否共享以及磁盘性能和流量如何计费。反过来，自建也意味着你要承担升级、备份、监控和故障处置。只有在扩展确实需要自主管理、工作负载适合稳定长期运行，且团队能承担数据库运维时，才值得把独享 AMD 物理机纳入方案比较。确认 PostgreSQL 目标版本与扩展验证计划后，再按实际内存和磁盘需求核对 OSFP Cloud 的可选配置；如果尚未完成恢复演练，优先补齐备份与回退方案，而不是先迁移生产数据。