待审查的扩展和逻辑复制对象

升级前请检查以下事项：

pg_repack

请在升级前删除 pg_repack，并在升级后重新创建该目录。pg_repack 使用了特定于版本的扩展以及客户端/服务器组件，这些组件必须与 PostgreSQL 的主版本号保持一致。

DROP EXTENSION pg_repack;

只有当您的工作负载仍然需要该扩展时，才需在升级后重新创建该扩展。

CREATE EXTENSION pg_repack;

old_snapshot

在升级前请删除 old_snapshot。 升级到 PostgreSQL 18后，请勿重新创建该文件，因为该文件已不再受支持。

DROP EXTENSION old_snapshot;

wal2json 复制槽

如果您使用 wal2json 进行逻辑解码，则必须在升级前删除所有相关的复制槽。 pg_upgrade 工具严格禁止在存在复制槽的情况下进行主版本升级，并将抛出严重错误并中止升级。

升级前：

1. 确保所有待处理的 WAL 数据均已处理完毕。
2. 停止使用该复制槽的应用程序。
3. 删除复制槽：

SELECT pg_drop_replication_slot('your_slot_name');

升级完成后，您可以根据需要重新创建复制槽。 请注意，wal2json 并非通过 CREATE EXTENSION 安装，而是通过数据库参数（wal_level、max_replication_slots、max_wal_senders ）和表权限进行配置，这些配置不会阻碍升级。

anon

升级前请先移除 anon 扩展，如果升级后仍需使用该扩展，请重新启用它。 在卸载 anon 之前，还需要执行一些额外步骤。

如果已安装 anon 扩展，请在执行升级之前完成以下步骤，并以管理员用户身份执行这些命令。

1. 删除所有屏蔽规则（如果已启用）。

   SELECT anon.remove_masks_for_all_columns();
   

2. 禁用角色屏蔽（如果任何角色被标记为屏蔽，升级可能会失败）。

   SECURITY LABEL FOR anon ON ROLE <role_name> IS NULL;
   

3. 使用级联选项删除 anon 扩展名。

   DROP EXTENSION anon CASCADE;
   

4. 如果某个实例中的多个数据库都安装了 anon 扩展，请针对每个数据库完成所述步骤。

5. 升级完成后，重新启用 anon 扩展，并根据需要重新应用屏蔽规则。

强烈建议在执行升级之前，在放弃扩展之前和之后验证数据，以确保屏蔽的一致性。

PostGIS

如果您使用的是 PostGIS,，请在升级 PostgreSQL 之前，先升级 PostGIS。

SELECT postgis_extensions_upgrade();

使用以下查询验证 PostGIS 扩展升级。

SELECT postgis_full_version();

Logical replication slots

请在升级前删除所有逻辑复制槽，并在升级后重新创建它们。 逻辑插槽与源服务器的状态相关联，应在升级后的实例上进行彻底重建。

SELECT pg_drop_replication_slot('<slot_name>');

准备工作

在开始升级程序之前，请考虑以下方面。

• 请通过 UI、API、CLI 或 Terraform 查看部署功能信息，以确认您的部署版本是否支持版本升级。

  示例：使用命令行界面（CLI）查询版本升级信息：

  ibmcloud cdb capability-show versions postgresql
  

• 在触发 IPU 之前，请务必查阅本主题中与预检查相关的要求。 IPU 直接在源部署上运行，不会创建新的实例。 为了保障客户的安全，该服务会在升级开始前进行预检查，若检测到风险，将阻止该操作。 请特别核对以下项目：

  • 您的部署最多包含 3 个成员。
  • 您的部署处于正常状态。
  • 您的部署环境至少有 10% 的可用磁盘空间。 IPU 预检查的默认最大允许磁盘使用率为 90%。
  • 您的部署未面临巨大的I/O压力。 IPU 预检查的默认最大允许 I/O 利用率为 90%。
  • 您的模式大小和对象数量均在默认预检查阈值范围内。 默认情况下，单个模式的大小不得超过 100 GB，且索引和序列的总数必须少于 50,000 个。
  • 您已在升级前完成了所有必要的扩展和逻辑复制槽清理工作。

• 每个主要版本都包含一些可能与旧版本不向后兼容的功能。 请查阅数据库供应商的 发布说明，了解可能影响您应用程序的任何变更。

• 不支持将部署降级到先前版本。

• 就地主版本升级一旦开始，便无法取消。

• 如果您没有最新的备份，请考虑在升级前进行备份。

此外，请注意，升级完成后，您的数据库将运行 PostgreSQL 的新主版本。 由于 PostgreSQL 将数据存储在特定版本的格式中，因此升级前的备份和PITR还原点属于较早版本的时间线，无法还原到已升级的版本中。 为确保新版本具备完整的还原和 PITR（特定时间点恢复）功能，请在升级完成后立即执行一次新的备份。 该备份将成为新版本时间轴上未来恢复操作的基础。

如果 IPU 操作失败，仍可使用升级前的有效备份配合 PITR 功能，将较早版本的 PostgreSQL 恢复到新实例中。

故障诊断

若应用程序在成功就地升级主版本后出现意外问题，且您需要回退至先前 PostgreSQL 版本，请联系我们的支持团队获取指导。 请勿自行启动 PITR 或恢复备份，否则可能会使恢复工作变得复杂。

就地重大升级将在所有预检通过后才会执行。 设置这些安全措施是为了保护您的部署，因为升级操作会直接作用于源实例。 如果升级被阻止，请检查以下方面：

• 成员数量：就地主版本升级支持最多包含 3 个成员的部署。 如果您的部署包含超过 3 个成员，则预检查会阻止升级。 无法通过 水平扩展 移除成员，因此请向 IBM Cloud 支持团队 提交支持工单，以减少成员数量，然后重试升级。
• 集群状态：确保 Patroni 集群运行正常，并且存在明确的领导者/副本状态。 若Patroni报告系统不稳定或故障转移状态，则无法进行升级操作。
• 磁盘空间：请确认是否有足够的可用空间。 该过程采用 pg_upgrade 链接模式，需要足够的余量。 若磁盘使用率超过配置的限制（默认：90%），请在重试前释放空间。
• 磁盘 I/O 负载：检查当前的 I/O 使用率和 IOPS。 当系统处于高负载状态时，升级操作将暂停，以防止性能下降或升级失败。
• 模式大小与对象数量：如前所述，模式大小直接影响就地主版本升级的持续时间。 确保任何单个模式都不超过最大大小（默认值：100 GB），且索引和序列对象的总数保持在限制范围内（默认值：50,000）。 大型架构或异常高的对象数量可能需要在升级前进行清理或优化。 pg_upgrade 通过创建新的系统表并直接复用旧的用户数据文件，实现快速升级。 创建这些系统表所需的时间与数据库对象的数量成正比。 资源消耗可通过 监控集成 进行评估。 如果并非所有数据库组件都可供升级，则升级任务将失败。 这可能是由于维护造成的。 因健康检查失败而失败的任务可稍后重试。 如果任务持续失败，请向 IBM Cloud 支持团队 提交支持工单。 如果某些检查与您的环境无关，但升级仍被阻止，请创建支持工单以获取进一步协助。

干运行提升和升级

要评估主要版本升级的影响，请触发干运行。 干运行会模拟提升和升级，并将结果打印到数据库日志中。 通过 日志分析集成 访问和查看数据库日志。 这将确保您当前使用其扩展运行的版本可以成功升级到预期版本。

必须在将 skip_initial_backup 设置为 false 并定义 version 的情况下运行干运行。

该命令如下所示:

curl -X POST \
  https://api.{region}.databases.cloud.ibm.com/v5/ibm/deployments/{id}/remotes/promotion \
  -H 'Authorization: Bearer <>'  \
 -H 'Content-Type: application/json' \
 -d '{
    "promotion": {
        "version": "14",
        "skip_initial_backup": false,
        "dry_run": true
    }
}' \