ApsaraDB RDS:Upgrade the major engine version of an ApsaraDB RDS for PostgreSQL instance

The PostgreSQL community releases a new major engine version every year and provides five years of technical support for each version. Each new version includes improvements in terms of functionality and performance compared with previous versions. The PostgreSQL community does not provide technical support for versions that were released five years ago or earlier, which increases the probability of performance risks and security risks of these versions.

ApsaraDB RDS for PostgreSQL provides a major engine version upgrade feature. This feature increases the performance and functionality of your database service and mitigate the risks that may be caused by an upgrade. To upgrade the major engine version of the original RDS instance by using this feature, perform the following steps:

1. Perform an upgrade check.

   Check whether the original RDS instance supports major engine version upgrades. Then, view the check report that is generated. If the check result in the upgrade check report is Fail, you cannot upgrade the major engine version.

2. Upgrade the major engine version.
   Note After you upgrade the major engine version of your RDS instance, the new major engine version may be incompatible with your workloads. Therefore, we recommend that you use the No cutting configuration method to test whether the new major engine version is compatible with your workloads before you perform the upgrade.
   1. Select the No cutting configuration method. ApsaraDB RDS creates an RDS instance that runs the new major engine version to test whether the new major engine version is compatible with your workloads.
   2. After the new major engine version passes the compatibility test, select the Cutover configuration method. ApsaraDB RDS creates an RDS instance that runs the new major version. After the data of the original RDS instance is migrated to the new RDS instance, ApsaraDB RDS switches your workloads over to the new RDS instance.

Usage notes

• The original RDS instance must meet the following requirements:
  • The instance runs PostgreSQL 14, PostgreSQL 13, PostgreSQL 12, PostgreSQL 11, or PostgreSQL 10, or PostgreSQL 9.4.
  • The original RDS instance runs RDS High-availability Edition or RDS Basic Edition. For more information, see RDS High-availability Edition and RDS Basic Edition.
  • The original RDS instance resides in a virtual private cloud (VPC).

    If the original RDS instance resides in the classic network, you must change the network type of the original RDS instance to VPC before you perform an upgrade. When you change the network type, clear Reserve original classic network endpoint. For more information about how to view or change the network type of an RDS instance, see Change the network type of an ApsaraDB RDS for PostgreSQL instance.

    Note If you select Reserve original classic network endpoint, you must wait until the retention period of the endpoint ends before you can start the upgrade task.
  • The original RDS instance cannot be a read-only instance and cannot be created in a dedicated cluster. For more information, see Overview of read-only ApsaraDB RDS for PostgreSQL instances and What is ApsaraDB for MyBase?
  • The ID of the original RDS instance does not start with pg-cn.
• An upgrade has the following impacts:
  • If you select the Cutover configuration method, ApsaraDB RDS needs to switch your workloads over to a new RDS instance during the upgrade process. The original RDS instance processes only read requests and a transient connection that lasts a few minutes occurs during the switchover. We recommend that you perform an upgrade during off-peak hours. If you select the No cutting configuration method, the original RDS instance is not affected.
    Note

    • The period of time during which the original RDS instance processes only read requests varies based on the number of database objects. If a large number of database objects exist in the original RDS instance, the original RDS instance processes only read requests for a long period of time. If millions of database objects exist, the original RDS instance may process only read requests for dozens of minutes or several hours. You can execute the SELECT count(1) FROM pg_class; statement to query the number of database objects in the original RDS instance.
    • The duration of a transient connection varies based on the interval at which Domain Name System (DNS) caches are refreshed. You can switch to a different vSwitch and estimate the intervals to refresh DNS caches on your database client based on the duration of the transient connection. For more information, see Switch an ApsaraDB RDS for PostgreSQL instance to a different vSwitch.
    • The period of time that is required to complete the upgrade varies based on the data volume and the number of database objects in the original RDS instance. If a large amount of data and a large number of database objects exist in the original RDS instance, the upgrade requires a long period to complete.
  • If the original RDS instance uses a parameter that is not supported by the new major engine version, the parameter is deleted from the new RDS instance. If the value of a parameter in the previous major engine version is not within the value range that is supported in the new major engine version, ApsaraDB RDS sets the parameter to the default value that is specified in the new major engine version.
  • The new RDS instance does not carry over the name, tags, alert rules, and backup data of the original RDS instance. For more information, see Add tags to ApsaraDB RDS for PostgreSQL instances, Configure an alert rule on an ApsaraDB RDS for PostgreSQL instance, and Back up an ApsaraDB RDS for PostgreSQL instance.
  • If the original RDS instance serves as the source RDS instance or destination RDS instance of a migration task that is created in the Data Transmission Service (DTS) console, you must re-create the migration task after you perform an upgrade. For more information about how to create a migration task in the DTS console, see What is DTS?
  • After an upgrade is complete, the read-only RDS instances and logical replication slots that you created in the original RDS instance remain attached to the original RDS instance rather than the new RDS instance. You must create read-only RDS instances and logical replication slots on the new RDS instance after the upgrade.
• If a read-only RDS instance is attached to the original RDS instance, you must perform the following operations before and after you perform an upgrade:
  1. Change the endpoint of the read-only RDS instance to the endpoint of the original RDS instance on your application.
     Note For service stability purposes, we recommend that you modify the endpoint configuration on your application during off-peak hours.
  2. Delete the read-only RDS instance.
  3. Upgrade the major engine version. For more information, see Procedure.
  4. After the upgrade is complete, create a read-only RDS instance on the new RDS instance. For more information, see Create a read-only ApsaraDB RDS for PostgreSQL instance.
  5. Change the endpoint of the original RDS instance to the endpoint of the new read-only RDS instance on your application.

Highlights

• Cross-version upgrade: You can upgrade the major engine version of the original RDS instance to a later version. For example, you can upgrade the major engine version from PostgreSQL 10 to PostgreSQL 13.
• Upgrade trial: You can use the No cutting configuration method to verify the feasibility of an upgrade without interruptions to your workloads on the original RDS instance.
• Smooth upgrade:
  • No application modification: You can use the Cutover configuration method to perform an upgrade. After the switchover is complete, you do not need to modify the endpoint configuration on your application. Your application automatically connects to the new RDS instance.
    Note If you use the Cutover configuration method to upgrade the major engine version of your original RDS instance, the virtual IP address (VIP) of the new RDS instance is different from that of the original RDS instance. If you configured the VIP of the original RDS instance on your application, you must change the VIP of the original RDS instance to the VIP of the new RDS instance on your application. We recommend that you configure the endpoint of the original RDS instance on your application. For more information about how to obtain the endpoint of an RDS instance, see View and change the endpoints and port numbers of an ApsaraDB RDS for PostgreSQL instance.
  • No downtime: An upgrade does not cause downtime on the original RDS instance. This mitigates the risks of service interruptions. However, the original RDS instance processes only read requests for a few minutes during the upgrade process. In addition, ApsaraDB RDS performs the upgrade by using instance cloning. The original RDS instance is not affected even if the upgrade fails.
  • Reserved instance configuration:
    • The new RDS instance carries over the IP address whitelists, parameter settings, and extensions of the original RDS instance. However, this does not apply to the extensions or parameters that are not supported in the new major engine version.
    • If the original RDS instance supports fully encrypted databases, the new RDS instance also supports fully encrypted databases and carries over the key that is used on the original RDS instance to encrypt data. For more information, see Create a fully encrypted database on an ApsaraDB RDS for PostgreSQL instance.

Billing rules

Procedure

1. If a read-only RDS instance is attached to the original RDS instance, perform the following steps before you upgrade the major engine version:
   1. Change the endpoint of the read-only RDS instance to the endpoint of the original RDS instance on your application.
      Note For service stability purposes, we recommend that you modify the endpoint configuration on your application during off-peak hours.
   2. Delete the read-only RDS instance.
2. Go to the Major Version Upgrade page.
   1. Access RDS Instances, select a region at the top, and then click the ID of the target RDS instance.
   2. In the left-side navigation pane, click Major Version Upgrade.
      

      Note

      • If Major Version Upgrade cannot be found, you can check whether your RDS instance meets all requirements that are described in Usage notes.
      • The major engine version upgrade feature is available only in the new ApsaraDB RDS console.
3. On the Upgrade Check tab, select the new major engine version and click Create upgrade check report. This process requires a few minutes.
   Note

   • Make sure that your RDS instance passes the upgrade check. Then, proceed with the subsequent steps.
   • If you execute the CREATE EXTENSION statement on your RDS instance after the new major engine version passes the upgrade check, you must perform an upgrade check again.

   If the upgrade check report indicates that your RDS instance fails the upgrade check, you can click View Information in the Report Content column to view the details about the report. For more information, see Introduction to the check report of a major engine version upgrade for an ApsaraDB RDS for PostgreSQL instance.

4. On the Upgrade Instance tab, read the warning that is displayed, select the new major engine version, and then click Continue to create upgrade instance.
5. In the message that appears, read the tips and click OK. Then, configure parameters. The following table describes only the crucial parameters.

   Parameter	Description
   Storage type	Select the storage type that is used for the new RDS instance. The major engine version upgrade feature is based on SSD snapshots. You can select a storage type based on the following conditions: If the original RDS instance uses standard SSDs, you can select Standard SSD. If the original RDS instance uses ESSDs, you can select ESSD PL1, ESSD PL2, or ESSD PL3. If the original RDS instance uses local SSDs, you can select ESSD PL1, ESSD PL2, or ESSD PL3.
   The Available Zone	Specify the zones and vSwitches of the new RDS instance and its secondary RDS instance. The zones that you specify can be different from the zones of the original RDS instance.
   For Available Zone
   Primary Instance Switch
   Standby Instance Switch
   Cutover configuration	Specify whether to enable ApsaraDB RDS to automatically switch your workloads over to a new RDS instance after the data of the original RDS instance is migrated to the new RDS instance. No cutting: ApsaraDB RDS does not automatically switch your workloads over to the new RDS instance. Before you perform an upgrade, we recommend that you select the No cutting configuration method to test whether the new major engine version is compatible with your workloads. If the new major engine version passes the compatibility test, you can release the new RDS instance. Then, you can select the Cutover configuration method to perform the upgrade. For more information, see Release or unsubscribe from an ApsaraDB RDS for PostgreSQL instance and Procedure. Note The data migration does not interrupt your workloads on the original RDS instance. If you select the No cutting configuration method, you must change the endpoint of the original RDS instance to the endpoint of the new RDS instance on your application after the data is migrated to the new RDS instance. For more information about how to view the endpoint of an RDS instance, see View and change the endpoints and port numbers of an ApsaraDB RDS for PostgreSQL instance. Cutover: ApsaraDB RDS automatically switches your workloads over to the new RDS instance. After the switchover is complete, you do not need to update the endpoint configuration on your application. Your application automatically connects to the new RDS instance. This configuration method is used to perform an upgrade after you verify that the new major engine version is compatible with your workloads. Note After the switchover is complete, you cannot roll your workloads back to the original RDS instance. Proceed with caution. During the switchover, the original RDS instance processes only read requests. We recommend that you perform the switchover during off-peak hours. If read-only RDS instances are attached to the original RDS instance, you cannot select the Cutover configuration method. In this case, you can upgrade the major engine version of the original RDS instance only by using the No cutting configuration method. In addition, the read-only RDS instances that are attached to the original RDS instance are not cloned. After the upgrade is complete, you must create read-only RDS instances that run the new major engine version for the new RDS instance. For more information, see Create a read-only ApsaraDB RDS for PostgreSQL instance.
   Cutover time	Specify the point in time when ApsaraDB RDS switches your workloads over to the new RDS instance after the data is migrated to the new RDS instance. Immediately: After the data is migrated to the new RDS instance, ApsaraDB RDS immediately switches your workloads over to the new RDS instance. Instance operation and maintenance time: ApsaraDB RDS switches your workloads over to the new RDS instance during the maintenance window that you specified. For more information, see Set the maintenance window of an ApsaraDB RDS for PostgreSQL instance. Note This parameter is available only when you set the Cutover configuration parameter to Cutover.
   Statistical information collection mode	The point in time at which ApsaraDB RDS collects the statistics of the new RDS instance. Collection before cutting: This option ensures the stability of your database service. If the original RDS instance contains a large amount of data, the upgrade may require a long period of time. Collection after cutting: This option accelerates the upgrade process. If you access tables for which no statistics are generated, the execution plans that you specify may be inaccurate. In addition, your database service may be unavailable during peak hours. Note If you select the No cutting configuration method, the Collection before cutting option specifies that ApsaraDB RDS collects the statistics of the new RDS instance before the new RDS instance starts to process read and write requests, and the Collection after cutting option specifies that ApsaraDB RDS collects the statistics of the new RDS instance after the new RDS instance starts to process read and write requests.
   Storage space	Specify the storage capacity of the new RDS instance. If the original RDS instance uses local SSDs, you can reduce the storage capacity of the RDS instance when you upgrade the major engine version of the RDS instance. The minimum value that you specify for the Storage space parameter must meet the following requirements: The minimum value is determined by the smaller one between the following values: The used storage of the original RDS instance multiplied by 120% in GB. If the result is not a multiple of 5, the obtained value is rounded up to a multiple of 5. Note You can view the used storage of the original RDS instance in the Disk Storage (MB) section on the Monitoring and Alerting page. For more information, see View the Enhanced Monitoring metrics of an ApsaraDB RDS for PostgreSQL instance. The storage capacity of the original RDS instance. The minimum value is greater than or equal to the minimum storage capacity of an ESSD. If the minimum value is smaller than the minimum storage capacity of an ESSD, you must use the minimum storage capacity of the ESSD as the minimum value. The following list provides the minimum storage capacities of ESSDs of different performance levels (PLs). ESSD of PL 1: 20 GB ESSD of PL2: 500 GB ESSD of PL3: 1,500 GB Note Examples: The storage capacity of the original RDS instance is 100 GB, 70 GB of storage is used, and ESSD PL1 is selected as the storage type when you upgrade the major engine version of the RDS instance. Calculation method: 70 × 120% = 84, rounded up to 85. The minimum value for the Storage space parameter is 85 GB. The storage capacity of the original RDS instance is 700 GB, 350 GB of storage is used, and ESSD PL2 is selected as the storage type when you upgrade the major engine version of the RDS instance. Calculation method: 350 × 120% = 420. The obtained value 420 GB is smaller than 500 GB that is supported by an ESSD of PL2. The minimum value for the Storage space parameter is 500 GB.
   Instance specification	Specify the instance type of the new RDS instance. For more information about the instance types that are supported, see Primary ApsaraDB RDS instance types.

6. Click Create now.
   The status of the original RDS instance changes to Migration in Progress. In addition, you can find a new RDS instance on the Instances page. The new RDS instance is in the Creating state. After the new RDS instance is created and the upgrade is complete, the statuses of the original RDS instance and new RDS instance change to Running. The time that is required to complete the upgrade varies based on the amount of data.

   Note After you create an upgrade task, you cannot modify or delete the task.
7. If a read-only RDS instance is attached to the original RDS instance and you deleted the read-only RDS instance in Step 1, perform the following steps after the upgrade:
   1. Create a read-only RDS instance for the new RDS instance. For more information, see Create a read-only ApsaraDB RDS for PostgreSQL instance.
   2. Change the endpoint of the original RDS instance to the endpoint of the new read-only RDS instance on your application. For more information, see Step 1.

What to do next

1. After you verify that your workloads run as expected on the new RDS instance, change the billing method of the new RDS instance to subscription. For more information, see Switch an ApsaraDB RDS for PostgreSQL instance from pay-as-you-go to subscription.
2. Release the original RDS instance. For more information, see Release or unsubscribe from an ApsaraDB RDS for PostgreSQL instance.
3. Create read-only RDS instances for the new RDS instance based on your business requirements because the new RDS instance does not carry over the read-only RDS instances of the original RDS instance. For more information, see Create a read-only ApsaraDB RDS for PostgreSQL instance.

Related operations

FAQ

• Can I change the configuration such as the specifications of an RDS instance during the major engine version upgrade of the RDS instance?

  No, you cannot change the configuration such as the specifications of an RDS instance during the major engine version upgrade of the RDS instance. You can change the configuration only after the major engine version is upgraded.

• Can the major engine version of an RDS instance be automatically upgraded?

  No, the major engine version of an RDS instance cannot be automatically upgraded.