PostgreSQL大版本升级中，最担心的往往不是拷贝数据文件的耗时，而是升级过程进行到一半时被系统目录校验拦下。pg_upgrade工具提供的--check参数可以在正式执行前完成一次只读预检，帮助确认当前数据目录与目标版本二进制之间的静态兼容性。预检阶段不会修改原库，也不会启动目标实例，它通过读取旧版本数据目录并与新版本系统表定义做比对，输出可能导致升级失败的条目。对于生产环境而言，这一步先跑一遍，能有效减少回滚和停机时间。
虽然很多资料把--check描述为升级前的必要动作，但真正理解它检查哪些项目、哪些问题不会检查，对于制定可靠的升级方案同样重要。下面从机制、失败项、实战流程和局限四个角度展开。
一、pg_upgrade --check 的检查机制与运行方式
pg_upgrade是PostgreSQL官方提供的二进制级大版本升级工具。它可以直接利用旧版本的数据文件，配合新版本的二进制程序完成系统表转换，避免全量逻辑导出导入。在正式执行升级前，pg_upgrade支持--check参数，用来做一次只读预检。这个参数不会修改旧数据目录，也不会在目标目录中创建新的数据库集群，它只是把升级过程中将要执行的校验逻辑提前跑一遍。
运行预检的基本命令格式如下：
# 假设旧版本为14，新版本为16 /usr/pgsql-16/bin/pg_upgrade \ --old-bindir /usr/pgsql-14/bin \ --new-bindir /usr/pgsql-16/bin \ --old-datadir /var/lib/pgsql/14/data \ --new-datadir /var/lib/pgsql/16/data \ --check
执行后，pg_upgrade会检查旧集群的系统目录、扩展、数据类型、索引存储格式、复制槽状态、预写日志等多个维度。如果发现会导致升级中断的问题，会以Fatal级别输出并返回非零退出码；如果只是潜在风险，会以Warning级别提示。预检通过的标准是退出码为0且没有Fatal条目。
需要注意的是，虽然是只读检查，但目标数据目录必须提前存在。通常需要先使用initdb初始化一个与目标版本一致的空集群，否则pg_upgrade无法完成对目标目录的版本识别。预检过程中旧库可以被正常访问，因为它不会锁定业务数据，也不要求数据库处于停机状态。不过，为了避免检查结果与实际升级时不一致，建议在业务低峰或计划停机窗口内执行。
二、预检常见的失败类型与修复方法
扩展版本不兼容是最容易触发的预检错误之一。PostgreSQL大版本升级后，许多扩展必须重新编译或安装对应版本。如果旧库中安装了某个扩展，而新版本环境没有对应的扩展文件，预检会直接报错并列出扩展名称。典型的输出类似：Your installation contains extensions that are not installed in the new cluster。修复方式通常是先在新版本环境中安装匹配的扩展，或者在旧库中删除不再需要的扩展。排查时可以执行下面的SQL确认旧库扩展列表：
SELECT extname, extversion FROM pg_extension ORDER BY extname;
哈希索引是另一类历史遗留问题。PostgreSQL 10之前的哈希索引不写WAL，也不支持流复制。如果旧库中还存在这类索引，升级后可能无法正常使用。预检会检测到旧格式的哈希索引并提示需要重建。处理办法是在旧库中执行REINDEX INDEX 索引名，或者直接删除并重建相关索引。对于较大的表，重建索引需要预留额外磁盘空间和时间。
复制槽与unlogged表也可能成为预检的拦路项。如果旧库开启了逻辑复制或物理复制，并且存在未消费的WAL，或者存在unlogged表，某些版本组合下pg_upgrade会拒绝继续。因为unlogged表在升级后可能丢失数据，复制槽则可能阻止必要的清理操作。修复思路是在升级前清空或删除复制槽，将unlogged表改为普通表并重新生成数据。预检会在输出中给出具体对象名称，按提示处理即可。
自定义数据类型和操作符也值得关注。如果业务中使用了基于旧版本二进制格式的自定义类型，而新版本对类型对齐或存储方式做了调整，预检可能发现不了深层兼容性问题，但某些扩展类型会直接报错。遇到这类情况，需要联系扩展维护者获取新版本，或者在测试环境先验证数据读写是否正常。
三、从预检到正式升级的完整操作流程
正式升级前，先完成基础准备：备份旧数据目录、确认新版本二进制包已安装、准备好与旧库相同的基础配置参数。接下来初始化一个空的目标集群：
/usr/pgsql-16/bin/initdb -D /var/lib/pgsql/16/data
然后执行带--check的预检命令。如果退出码为0，可以进入下一步；如果出现Fatal，需要根据错误信息逐项修复。修复完成后再次执行预检，直到没有任何致命错误。每次修复后重新跑预检很重要，因为某些对象的修复可能影响其他依赖项。
预检通过后，可以执行真正的升级命令。生产环境常用--link模式减少文件拷贝时间，同时用--jobs参数并行处理多个数据库：
/usr/pgsql-16/bin/pg_upgrade \ --old-bindir /usr/pgsql-14/bin \ --new-bindir /usr/pgsql-16/bin \ --old-datadir /var/lib/pgsql/14/data \ --new-datadir /var/lib/pgsql/16/data \ --link \ --jobs=4
升级完成后，还需要运行analyze_new_cluster.sh脚本来刷新统计信息，并检查数据库日志确认没有异常。如果确认新集群稳定运行，再删除旧数据目录以释放空间。整个流程中，预检承担了风险前置的作用，但它不能替代测试环境验证和业务回归。
四、预检的局限和补充验证建议
pg_upgrade --check 主要针对静态兼容性问题，比如扩展缺失、索引格式错误、复制槽冲突等。它不会检查应用SQL在新版本下的执行计划变化，也不会发现统计信息失效导致的性能下降。即使预检全部通过，升级后仍可能出现查询变慢、锁等待增加、插件运行时报错等问题。
因此，建议在预检基础上增加两层验证。第一层是在测试环境完整模拟升级流程，记录每个步骤的耗时和错误，同时跑一遍核心业务SQL。第二层是在生产升级后保留一段观察期，重点关注日志中的慢查询、连接异常和空间增长。对于使用了第三方扩展的环境，还要提前确认扩展对新版本的官方支持情况，避免出现预检能通过但运行时崩溃的边界场景。
预检的价值在于把已知的硬性兼容问题挡在升级之前，而不是保证升级后业务零风险。理解这一点，才能更合理地安排停机窗口和回退方案。
