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

升级前请检查以下事项：

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>');

准备工作

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

• 请通过 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
    }
}' \