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

升级前请检查以下事项：

扩展

• pg_repack
• old_snapshot
• wal2json
• anon
• PostGIS

复制槽

• Logical replication slots

应用程序依赖项 如果您删除了应用程序所依赖的扩展或复制对象，请在继续升级之前验证数据流和应用程序的行为。 此外，还应考虑依赖于 PostgreSQL 特定功能的应用程序逻辑可能出现的问题。

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,，请先升级 PostGIS，然后再升级 PostgreSQL。

SELECT postgis_extensions_upgrade();

使用以下查询来验证 PostGIS 扩展程序的升级情况。

SELECT postgis_full_version();

Logical replication slots

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

SELECT pg_drop_replication_slot('<slot_name>');

逻辑复制槽

在升级前删除所有逻辑复制槽，升级后再重新创建它们。 逻辑复制槽与源服务器的状态相关联，必须在升级后的实例上重新创建。

SELECT pg_drop_replication_slot('<slot_name>');

准备工作

在开始升级之前，请确认以下事项：

• 请通过 UI、API、CLI 或 Terraform 验证您的部署是否支持版本升级。

  示例（CLI）：

  ibmcloud cdb capability-show versions postgresql
  

• 查看预核查要求。 升级在源部署环境中运行， 如果检测到风险，则会暂停。 确保：

  • 部署状态正常
  • 至少有 10% 的可用磁盘空间
  • I/O 利用率低于 90%
  • 模式大小和对象数量均在支持范围内
  • 所需的扩展和逻辑复制槽清理已完成

• 请查阅《 https://www.postgresql.org/docs/release/ 》，了解可能影响您应用程序的兼容性变更。

• 不支持降级到较早的版本。

• 就地升级一旦开始，就无法取消。

• 升级前，请确保有最新的备份。

Gen2 从 PostgreSQL 18开始。 随着对新版本的支持陆续推出，相应的升级路径也将陆续添加。 关于早期版本（14–17），请参阅 /docs/databases-for-postgresql?topic=databases-for-postgresql-upgrading。

升级完成后，您的部署将运行 PostgreSQL 的新主版本。 升级前的备份和PITR还原点属于较早版本的时间线，无法还原到已升级的版本中。

为了在新版本中保持还原和PITR功能，请在升级完成后立即进行备份。 此备份将成为未来恢复操作的基准。

如果升级失败，仍可利用升级前的备份通过 PITR 将早期版本恢复到新的部署环境中。

故障诊断

如果升级成功后出现问题，且您需要恢复到上一版本，请联系 IBM Cloud® 技术支持以获取指导。 请勿在无人指导的情况下执行 PITR 或恢复操作，否则可能会使恢复过程变得复杂。

只有在所有预检查均通过后，才会执行升级。 如果升级受阻，请确认：

• 集群健康状况（Patroni状态为稳定）
• 足够的可用磁盘空间
• 可接受的磁盘I/O利用率
• 模式大小和对象数量限制

大型模式和庞大的对象数量可能会延长升级所需的时间。

如果升级尝试仍失败，请通过 https://cloud.ibm.com/login?redirect=%2Funifiedsupport%2Fsupportcenter 提交支持工单。

对促销和升级进行模拟演练

要评估主要版本升级的影响，请触发一次模拟运行。 模拟运行会模拟晋升和升级过程，并将结果写入数据库日志。 通过 “日志分析”集成 访问并查看您的数据库日志。 这可确保您当前运行的版本及其扩展能够成功升级到您目标的版本。

在进行干跑时，必须将 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
    }
}' \