# 通过界面升级大版本 #### 操作场景 用户可以升级RDS for PostgreSQL实例的大版本，体验更丰富的版本能力。 如需使用大版本升级功能，请[提交工单](https://console.huaweicloud.com/ticket/?locale=zh-cn#/ticketindex/createIndex)申请。 #### 升级方案 RDS for PostgreSQL支持通过界面升级引擎大版本，目前支持以下两种升级方式： - [不割接模式]：不割接模式的大版本升级对业务没有影响，大版本升级过程中会快照一个新的实例，原实例不做任何操作。使用新实例进行大版本升级操作，升级完成后，用户可以连接新实例进行业务兼容性测试。大版本升级可能导致业务兼容性问题，强烈建议业务进行充分兼容性测试，测试通过后，再进行割接模式升级。 - [割接模式]：割接模式的大版本升级过程中会快照一个新的实例，原实例会设置为只读，并存在业务分钟级闪断。使用新实例进行大版本升级操作，升级完成后自动切换VIP（Virtual IP Address）和内网域名，用户业务会自动连接到新的高版本实例，完成整个升级流程。升级完成后，原实例依然为只读状态，不会自动解除。 #### 介绍视频 #### 版本限制 - 以下版本的实例作为源实例支持大版本升级： - 对于PostgreSQL 9.5版本，小版本为9.5.25及以上。 - 对于PostgreSQL 9.6版本，小版本为9.6.24及以上。 - 对于PostgreSQL 10版本，小版本为10.21及以上。 - 对于PostgreSQL 12版本，小版本为12.6.3及以上。 - 对于PostgreSQL 13版本，小版本为13.2.3及以上。 - 对于PostgreSQL 14版本，小版本为14.4及以上。 - 对于PostgreSQL 15版本，小版本为15.4及以上。 - 支持PostgreSQL 16和17版本，小版本没有限制。 - 对于PostgreSQL 11版本和增强版，不支持大版本升级。 #### 升级须知 表1升级须知 | 阶段 | 注意事项 | 功能限制 | |:---|:---|:---| | 升级前 | - 由于操作系统限制，部分实例暂不支持大版本升级，具体以实际["大版本升级"]界面为准。部分12及以上版本的实例支持跨操作系统进行大版本升级，但升级后无法将实例备份恢复到已有实例。如需跨操作系统进行大版本升级请[提交工单](https://console.huaweicloud.com/ticket/?locale=zh-cn#/ticketindex/createIndex)申请。 - 大版本升级前，需要先进行升级检查，如果在有效期内没有检查成功的报告，则不允许进行大版本升级。 - 大版本升级检查会有一定资源开销，请选择业务低峰期操作。 对包含大量表级对象（例如10万+表、视图、函数等对象）的实例，系统资源（尤其是 CPU 和 I/O）会出现明显的阶段性上涨。资源消耗主要为预检验阶段会在主节点调用pg_upgrade工具逐项对比升级前后的元数据信息。 | - 已搭建容灾关系的容灾主实例仅支持不割接模式升级，如需使用割接模式升级，需要先[解除容灾关系](https://support.huaweicloud.com/usermanual-rds-pg/rds_pg_02_0052.html)，待割接模式升级完成后重新搭建容灾关系。 - 已搭建容灾关系的灾备实例不支持大版本升级，如需升级需要先[解除容灾关系](https://support.huaweicloud.com/usermanual-rds-pg/rds_pg_02_0052.html)。 - 当数据库进行大版本升级时，部分已安装的插件会导致升级任务失败，请先卸载相关插件后再进行大版本升级。详见[升级插件限制说明]。 | | 升级中 | - 如果大版本升级检查失败且检查报告无内容，请[提交工单](https://console.huaweicloud.com/ticket/?locale=zh-cn#/ticketindex/createIndex)处理。 - 使用割接方式升级，原实例会设置为只读，在升级完成后只读不会自动解除。升级过程中，会造成业务分钟级闪断，请在业务低峰期进行升级。使用不割接方式升级时，没有任何影响。 只读设置通过参数"default_transaction_read_only"控制，请检查业务中是否存在修改参数"default_transaction_read_only"的情况，如果存在，则会导致在割接期间实例插入的数据在升级完成后丢失。 | - postgis插件不支持大版本升级。 - 只读实例无法进行大版本升级。若当前实例存在只读实例，大版本升级完成后，只读实例不会同步升级，需要重新创建，请参见[创建只读实例](https://support.huaweicloud.com/usermanual-rds-pg/rds_add_read_replica_pg.html)。 | | 升级后 | - 大版本升级完成后，会新建一个实例，原有实例依然保留并计费，在业务稳定后您可以选择释放原有实例。 - 大版本升级完成后，相较原低版本参数模板，高版本参数有以下变化： - 高版本参数模板中新增的参数用所选参数模板的值。 - 高版本参数模板中已有参数的值和低版本保持一致，如果该值不在高版本参数取值范围内，则使用高版本参数模板的值。 - 高版本不支持的原低版本参数会自动删除。 - 特殊参数：wal_keep_segments（RDS for PostgreSQL 13以下版本）和wal_keep_size（13及以上版本）都是WAL日志保留相关参数。将13以下版本的实例升级到13及以上版本后，wal_keep_size参数会替代wal_keep_segments参数，并自动换算参数值。 | - 割接模式下，大版本升级完成后，若发现业务不兼容，需要回退。请[提交工单](https://console.huaweicloud.com/ticket/?locale=zh-cn#/ticketindex/createIndex)为您解除原实例只读状态后，您可继续使用原实例。 - 割接模式下，升级完成后新增的数据，原实例不会进行自动同步。 - 大版本升级后，原实例的审计日志、错误日志、慢日志仍保留在原实例，新实例只能查看该实例后续生成的日志记录。 - 若当前实例存在灾备实例，大版本升级完成后，灾备实例不会同步升级，灾备关系会断开，需要使用同版本实例重新搭建灾备关系。 - 大版本升级不会升级插件版本，参考[支持的插件列表](https://support.huaweicloud.com/usermanual-rds-pg/rds_09_0045.html)，若新版本支持更高版本的插件，您可使用命令**ALTER EXTENSION extension_name UPDATE TO 'new_version';**更新插件，或者卸载并重新安装最新版本插件。 | #### 升级插件限制说明 **在[大版本升级检查]成功后，** 如果大版本升级路径中，实例安装有[表2]中的插件，需要提前卸载，在大版本升级完成后再重新安装。否则，会导致实例升级失败，或者实例升级后由于插件无法升级导致插件不能正常使用。 表2插件限制说明 | 起始版本 | 目标版本 | 升级前需要提前卸载，否则会导致实例升级失败的插件 | 实例升级后无法正常使用的插件 | |:---|:---|:---|:---| | 12 | 13 | orafce, postgis_sfcgal | address_standardizer_data_us, pgaudit | | 12 | 14 | orafce, postgis_sfcgal | anon, pgaudit | | 12 | 15 | orafce, postgis_sfcgal | anon, pgaudit | | 12 | 16 | orafce, postgis_sfcgal, pgl_ddl_deploy | anon, pgaudit | | 12 | 17 | orafce, pgl_ddl_deploy, postgis, postgis_raster, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal, pg_track_settings | anon, pgaudit | | 12 | 18 | orafce, pgl_ddl_deploy, postgis, postgis_raster, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal, pg_track_settings | anon, pgaudit | | 13 | 14 | - | anon, pgaudit, pg_stat_kcache, postgis, postgis_raster, address_standardizer, address_standardizer_data_us, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal | | 13 | 15 | - | anon, pgaudit, pg_stat_kcache | | 13 | 16 | pgl_ddl_deploy | anon, pgaudit, pg_stat_kcache | | 13 | 17 | pgl_ddl_deploy, postgis, postgis_raster, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal, pg_track_settings | anon, pgaudit, pg_stat_kcache, powa | | 13 | 18 | pgl_ddl_deploy, postgis, postgis_raster, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal, pg_track_settings | anon, pgaudit, pg_stat_kcache, powa | | 14 | 15 | - | pgaudit, pg_stat_kcache | | 14 | 16 | pgl_ddl_deploy | pgaudit, pg_stat_kcache | | 14 | 17 | pgl_ddl_deploy, postgis, postgis_raster, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal, pg_track_settings | pgaudit, pg_stat_kcache, powa | | 14 | 18 | pgl_ddl_deploy, postgis, postgis_raster, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal, pg_track_settings | pgaudit, pg_stat_kcache, powa | | 15 | 16 | pgl_ddl_deploy | pgaudit | | 15 | 17 | pgl_ddl_deploy, postgis, postgis_raster, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal, pg_track_settings | pgaudit, pg_stat_kcache, powa | | 15 | 18 | pgl_ddl_deploy, postgis, postgis_raster, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal, pg_track_settings | pgaudit, pg_stat_kcache, powa | | 16 | 17 | postgis, postgis_raster, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal, pg_track_settings | pgaudit, pg_stat_kcache, powa | | 16 | 18 | postgis, postgis_raster, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal, pg_track_settings, pg_tde | pgaudit, pg_stat_kcache, powa | | 17 | 18 | postgis, postgis_raster, postgis_topology, postgis_tiger_geocoder, postgis_sfcgal, pg_track_settings, pg_tde | pgaudit, pg_stat_kcache, powa | #### 计费方式 大版本升级后产生的新实例为按需计费，在确认业务平稳运行后，您可以执行以下操作： - 将新实例转为包年/包月计费，请参见[按需计费转包年/包月](https://support.huaweicloud.com/price-rds-pg/rds_00_0010.html)。 - 如果原实例为按需计费，将原实例释放，请参见[删除按需实例](https://support.huaweicloud.com/usermanual-rds-pg/rds_09_0025.html)。 - 如果原实例为包年/包月计费，将原实例退订，请参见[退订包周期实例](https://support.huaweicloud.com/usermanual-rds-pg/rds_pg_05_0056.html)。包年/包月实例未到期前，退订可能会存在费用损失，请在升级前确认[退订规则](https://support.huaweicloud.com/usermanual-billing/unsubscription_topic_20000083.html)。 #### 操作步骤 - [不割接模式升级] 1. [登录RDS管理控制台](https://console.huaweicloud.com/rds/#/rds/management/list)。 2. 单击管理控制台左上角的![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002606863935.png)，选择区域。 3. 在实例列表，单击实例名称，进入实例的"概览"页面。 4. 在左侧导航栏，选择"大版本升级"。 ![](https://support.huaweicloud.com/usermanual-rds-pg/public_sys-resources/note_3.0-zh-cn.png) 如果没有看到"大版本升级"页签，请[提交工单](https://console.huaweicloud.com/ticket/?locale=zh-cn#/ticketindex/createIndex)申请。 图1大版本升级 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002532184688.png "点击放大") 5. 在"大版本升级"页面，选择目标升级版本，单击"下一步"。 图2升级信息 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002532023320.png "点击放大") 6. 在预检查页面，启动升级前预检查，等待几分钟，查看预检查成功。 图3预检查 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002532028202.png "点击放大") ![](https://support.huaweicloud.com/usermanual-rds-pg/public_sys-resources/note_3.0-zh-cn.png) - 升级检查成功后，如果有新创建插件，可能会因为不兼容，导致升级失败，建议重新进行升级检查。详见[升级插件限制说明]。 - 若升级检查失败，您可在检查历史中[查看升级检查报告]，根据报告内容修改数据中存在的不兼容情况。 7. 预检查成功后，选择参数模板和不割接模式，一键输入"升级"，单击"立即升级"。 图4不割接模式 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002537466423.png "点击放大") 8. 确认升级信息后，单击"提交"，开始大版本升级。 图5确认升级信息 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002532188310.png "点击放大") 9. 升级完成后，可以看到新创建的目标版本实例，用户可以连接新实例进行业务兼容性测试。 图6查看升级结果 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002563068817.png "点击放大") - [割接模式升级] 1. [登录RDS管理控制台](https://console.huaweicloud.com/rds/#/rds/management/list)。 2. 单击管理控制台左上角的![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002606863935.png)，选择区域。 3. 在实例列表，单击实例名称，进入实例的"概览"页面。 4. 在左侧导航栏，选择"大版本升级"。 ![](https://support.huaweicloud.com/usermanual-rds-pg/public_sys-resources/note_3.0-zh-cn.png) 如果没有看到"大版本升级"页签，请[提交工单](https://console.huaweicloud.com/ticket/?locale=zh-cn#/ticketindex/createIndex)申请。 图7大版本升级 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002532024754.png "点击放大") 5. 在"大版本升级"页面，选择目标升级版本，单击"下一步"。 图8升级信息 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002532184646.png "点击放大") 6. 在预检查页面，启动升级前预检查，等待几分钟，查看预检查成功。 图9预检查 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002532188146.png "点击放大") ![](https://support.huaweicloud.com/usermanual-rds-pg/public_sys-resources/note_3.0-zh-cn.png) - 升级检查成功后，如果有新创建插件，可能会因为不兼容，导致升级失败，建议重新进行升级检查。详见[升级插件限制说明]。 - 若升级检查失败，您可在检查历史中[查看升级检查报告]，根据报告内容修改数据中存在的不兼容情况。 7. 预检查成功后，选择参数模板和割接模式，以及统计信息收集模式，一键输入"升级"，单击"立即升级"。 图10割接模式 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002505506674.png "点击放大") 大版本升级时，不会自动同步优化器统计信息，因此需要在升级完成后进行统计信息收集。 - 割接前收集：可以保证业务稳定性。如果实例数据量太大可能会导致升级时间较久。 - 割接后收集：实例升级速度较快。升级后访问未生成统计信息的表可能导致执行计划不准确，业务高峰期还可能导致数据库宕机。 8. 确认升级信息后，单击"提交"，开始大版本升级。 图11确认升级信息 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002532028398.png "点击放大") 9. 升级完成后，可以看到新创建的目标版本实例，用户业务会自动切换到新实例。 图12查看升级结果 ![](https://support.huaweicloud.com/usermanual-rds-pg/zh-cn_image_0000002532028872.png "点击放大") #### 查看升级检查报告和升级报告 当升级检查失败或升级失败时，可通过升级检查报告或升级报告来分析失败的原因，步骤如下： 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](https://support.huaweicloud.com/usermanual-rds-pg/rds_09_0070.html#rds_09_0070__section168162616349)中删除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" ``` 3. 升级检查失败后，界面出现如下报错的处理方法。 报错信息： ``` Relation names for OID 16479 in database postgres do not match toast: relname recyclebin_tb_1;Relation names for OID 16472 in database postgres do not match toast: relname tb_toast; ``` 处理方法（执行期间涉及表对象变更，请根据实际情况停止向表中写入业务）： 1. 备份异常表，下面以表public.tb_toast为例。 ``` CREATE TABLE public.tb_toast_bak AS SELECT * FROM public.tb_toast; ``` 2. [卸载recyclebin插件](https://support.huaweicloud.com/usermanual-rds-pg/rds_09_0070.html)，卸载后会自动清理回收站对象（如 recyclebin_tb_1）。 3. 删除异常表。 ``` DROP TABLE public.tb_toast; ``` 4. 恢复原表名。 ``` ALTER TABLE public.tb_toast_bak RENAME TO tb_toast; ``` 5. 重新执行升级检查，确认界面不再出现"do not match toast"报错。