通过界面升级大版本

操作场景

RDS for PostgreSQL支持通过界面升级大版本，目前支持以下两种升级方式：

• 非割接模式：用于新版本的业务兼容性测试。大版本升级可能会导致业务兼容性问题，因此建议在割接模式升级前，先进行充分的兼容性测试。使用非割接模式升级，不会影响原有实例。
• 割接模式：在割接升级过程中，原实例将被设置为只读模式，并可能出现分钟级别的业务中断。升级完成后，系统会自动交换实例的VIP，业务无需进行任何更改即可完成升级。升级完成后，原实例仍保持只读状态，不会自动解除。

约束限制

• 以下版本的实例支持进行大版本升级：
  • 对于PostgreSQL 9.5版本，小版本为9.5.25及以上。
  • 对于PostgreSQL 9.6版本，小版本为9.6.24及以上。
  • 对于PostgreSQL 10版本，小版本为10.21及以上。
  • 对于PostgreSQL 12版本，小版本为12.7及以上。
  • 对于PostgreSQL 13版本，小版本为13.3及以上。
  • 对于PostgreSQL 14版本，小版本为14.4及以上。
  • 对于PostgreSQL 15版本，小版本为15.4及以上。
  • PostgreSQL 16和PostgreSQL 17版本。
• 由于操作系统限制，部分实例暂不支持进行大版本升级，具体以实际界面为准。
• 大版本升级前，需要先进行升级检查，如果在有效期内没有检查成功的报告，则不允许进行大版本升级。

升级插件限制说明

在大版本升级检查成功后，如果大版本升级路径中，实例安装有表1中的插件，需要提前卸载，在大版本升级完成后再重新安装。否则，会导致实例升级失败，或者实例升级后由于插件无法升级导致插件不能正常使用。

注意事项

• PostgreSQL 10和PostgreSQL 11版本已下线，存量实例的备份恢复，规格变更、磁盘缩容、创建只读、单转主备等功能将不可用，建议您尽快进行大版本升级。

• 割接模式下，完成大版本升级后，如果发现业务不兼容，需要进行回退。请先联系客服解除原实例只读状态，然后您可以继续使用原实例。
  

  升级完成后新增的数据，原实例不会进行自动同步。

• 完成大版本升级后，会创建一个新实例，而原有实例继续保留并计费。在业务稳定后您可以选择释放原有实例。
• 大版本升级后，原实例的审计日志、错误日志、慢日志仍保留在原实例中，而新实例只能查看该实例后续生成的日志记录。
• 只读实例无法进行大版本升级。如果当前实例存在只读实例，在完成大版本升级后，只读实例将不会自动同步升级，需要重新创建，请参见创建只读实例。
• 如果当前实例存在灾备实例，在完成大版本升级后，灾备实例将不会同步升级，灾备关系会中断，需要使用相同版本的实例重新建立灾备关系。
• 大版本升级会有以下影响：
  使用割接方式升级时，升级过程中原实例将被设置为只读模式，并可能导致业务出现分钟级别的中断。建议在业务低峰期执行升级。而采用非割接方式升级，则不会对业务造成任何影响。

  

  只读设置通过参数“default_transaction_read_only”控制，请检查业务中是否存在修改参数“default_transaction_read_only”的情况，如果存在，则会导致在割接期间实例插入的数据在升级完成后丢失。

• 完成大版本升级后，与原低版本参数模板相比，高版本参数发生了以下变化：
  • 在高版本的参数模板中，新增的参数将使用所选参数模板的值。
  • 在高版本参数模板中，已有的参数值应与低版本保持一致。但如果该值不在高版本参数的取值范围内，则应采用高版本参数模板中的值。
  • 在高版本参数模板中，不支持的原低版本参数将被自动删除。
• 大版本升级不会升级插件版本，参考支持的插件列表，如果新版本支持更高版本的插件，您可以使用以下命令更新插件，或者卸载并重新安装最新版本插件。

  ALTER EXTENSION extension_name UPDATE TO 'new_version';

  

  当数据库进行大版本升级时，部分已安装的插件会导致升级任务失败，请先卸载相关插件后再进行大版本升级。

  不支持大版本升级的插件包括：postgis

非割接模式升级

1. 登录管理控制台。
2. 单击管理控制台左上角的，选择区域和项目。
3. 单击页面左上角的，选择“数据库 > 云数据库 RDS”，进入RDS信息页面。
4. 在实例列表，单击实例名称，进入实例的基本信息页面。
5. 在左侧导航栏，选择“大版本升级”。
6. 在“大版本升级”页面，单击“大版本升级”，选择目标升级版本，单击“下一步”。
7. 在预检查页面，单击“立即检查”启动升级前预检查，等待几分钟，查看预检查结果。
   

   • 升级检查成功后，如果有新创建插件，可能会因为不兼容，导致升级失败，建议重新进行升级检查。详情请参见升级插件限制说明。
   • 如果升级检查失败，您可以在检查历史中查看升级检查报告，根据报告内容修改数据中存在的不兼容情况。

8. 预检查结果成功后，单击“下一步”。
9. 选择参数模板和不割接模式，一键输入“升级”，单击“立即升级”。
10. 确认升级信息后，单击“提交”，开始大版本升级。
11. 升级完成后，可以看到新创建的目标版本实例，用户可以连接新实例进行业务兼容性测试。

割接模式升级

1. 登录管理控制台。
2. 单击管理控制台左上角的，选择区域和项目。
3. 单击页面左上角的，选择“数据库 > 云数据库 RDS”，进入RDS信息页面。
4. 在实例列表，单击实例名称，进入实例的基本信息页面。
5. 在左侧导航栏，选择“大版本升级”。
6. 在“大版本升级”页面，单击“大版本升级”，选择目标升级版本，单击“下一步”。
7. 在预检查页面，单击“立即检查”启动升级前预检查，等待几分钟，查看预检查结果。
   

   • 升级检查成功后，如果有新创建插件，可能会因为不兼容，导致升级失败，建议重新进行升级检查。详情请参见升级插件限制说明。
   • 如果升级检查失败，您可以在检查历史中查看升级检查报告，根据报告内容修改数据中存在的不兼容情况。

8. 预检查结果成功后，单击“下一步”。
9. 选择参数模板和割接模式，以及统计信息收集模式，一键输入“升级”，单击“立即升级”。

   大版本升级时，不会自动同步优化器统计信息，因此需要在升级完成后进行统计信息收集。

   • 割接前收集：可以保证业务稳定性。如果实例数据量太大可能会导致升级时间较久。
   • 割接后收集：实例升级速度较快。升级后访问未生成统计信息的表可能导致执行计划不准确，业务高峰期还可能导致数据库无法正常使用。

10. 确认升级信息后，单击“提交”，开始大版本升级。
11. 升级完成后，可以看到新创建的目标版本实例，用户业务会自动切换到新实例。

查看升级检查报告和升级报告

当升级检查失败或升级失败时，可通过升级检查报告或升级报告来分析失败的原因，步骤如下：

1. 查看“pg_upgrade_internal.log”。

   “pg_upgrade_internal.log”为升级检查报告或升级报告的主要日志文件，当升级失败时，首先查看该文件内容，查看相关报错。常见的报错如下：

   • A list of problem libraries is in the file: loadable_libraries.txt

     存在高版本不兼容的插件，插件列表记录在“loadable_libraries.txt”文件中。

   • A list of tables with the problem is in the file: tables_with_oids.txt

     建表时声明了WITH OIDS，该声明在PostgreSQL 12或以上版本不支持，相关表被记录在“tables_with_oids.txt”文件中。

   • Consult the last few lines of "pg_upgrade_server.log" for the probable cause of failure.

     升级检查时，高版本启动失败，具体原因在“pg_upgrade_server.log”报告项中查看。

   • Consult the last few lines of "pg_upgrade_dump_xxxx.log" for the probable cause of failure.

     升级过程中，pg_dump失败，具体原因在“pg_upgrade_dump_xxxx.log”报告项中查看。

   • The source cluster contains roles starting with "pg_"

     存在高版本不兼容的用户，在高版本中不允许存在“pg_”开头的用户，需要先删除或重命名原实例中“pg_”开头的用户。

   • A list of the problematic objects is in the file: incompatible_polymorphics.txt

     存在高版本不兼容的函数参数类型“anyarray”或“anyelement”，需要在升级之前删除对应函数的定义并且在升级后恢复它们，同时修改参数类型（“anyarray”修改为“anycompatiblearray”，“anyelement”修改为“anycompatible”），具体的函数对象记录在“incompatible_polymorphics.txt”文件中。

2. 根据“pg_upgrade_internal.log”中的信息，在对应的报告项中分析原因。
   • loadable_libraries.txt

     展示不兼容的library，通常对应了不兼容的插件。排查“loadable_libraries.txt”中列出的插件，根据实际需要进行评估是否删除，建议在不影响业务稳定的情况下删除后升级。

   • tables_with_oids.txt

     展示声明了WITH OIDS的表清单。排查“tables_with_oids.txt”中列出的表，评估业务代码中是否对OID有依赖，确认不影响业务之后，执行以下SQL：

     ALTER TABLE {table_name} SET WITHOUT OIDS;

   • pg_upgrade_server.log

     查看“pg_upgrade_server.log”的最后几行信息，如果存在如下报错，则说明高版本中不存在xxx插件，根据实际业务，评估可删除xxx插件，并在shared_preload_libraries中删除xxx，建议在不影响业务稳定的情况下删除后升级。

     FATAL: could not access file "xxx": No such file or directory.

     示例：

     FATAL: could not access file "pg_pathman": No such file or directory.

   • pg_upgrade_dump_xxxx.log
     • 查看“pg_upgrade_dump_xxxx.log”最后几行信息，如果存在如下报错，则说明当前实例中表的数量过多，按照提示需适当增加max_locks_per_transaction参数值，并重新升级。

       pg_dump: error: query failed: ERROR: out of shared memory
       HINT: You might need to increase max_locks_per_transaction.
       pg_dump:error: query was: LOCK TABLE "xxx"."xxx" IN ACCESSSHARE MODE

     • 查看“pg_upgrade_dump_xxxx.log”最后几行信息，如果存在如下报错，是因为当前实例中存在插件pgl_ddl_deploy，该插件高低版本不兼容，导致升级失败。请根据升级插件限制说明排查实例中是否存在其他不兼容的三方插件（部分三方插件的兼容性无法通过升级检查识别出来），根据实际需要进行评估是否删除，建议在不影响业务稳定的情况下删除后升级。

       pg_restore: error: could not execute query: ERROR: could not find function "xxx" in file xxx
       Command was: CREATE FUNCTION "pgl_ddl_deploy"."xxx"