Upgrade procedure

Prerequisite: Verify the PolarDB service-linked role

Before performing a major version upgrade by using the logical migration method (DTS data synchronization), verify that a PolarDB service-linked role exists and that you have granted DTS permissions to access cloud resources.

• Check if the service-linked role for PolarDB has been created

  1. With your Alibaba Cloud account (primary account), go to the Identity Management > Role page in the RAM console.

  2. Check whether a service-linked role named AliyunServiceRoleForPolarDB exists in the role list, as shown in the following figure.

     • If it exists, skip this check.

     • If it does not exist, proceed to the next step.

  3. Click Create Role. On the Create Role page, click Create Service-linked Role in the upper-right corner.

  4. On the Create Service-linked Role page, select AliyunServiceRoleForPolarDB for Trusted Cloud Service, and then click Create Service-linked Role to complete the creation.

• Check if DTS has been granted permissions to access cloud resources

  The following sections describe how to check the authorization result and use fast authorization. For more information, see Grant DTS permissions to access cloud resources.

  Check authorization results

  1. With your Alibaba Cloud account (primary account), go to the Identity Management > Role page in the RAM console.

  2. Check whether a role named AliyunDTSDefaultRole exists in the role list, as shown in the following figure.

     1. If it does not exist, go to Fast authorization.

     2. If it exists, continue to the next step to check its permissions.

  3. Click the role name to view the details of AliyunDTSDefaultRole.

     • The AliyunDTSDefaultRole role is successfully authorized if it meets the following conditions:

       • The system policy AliyunDTSRolePolicy is listed under Permissions.

         

       • The Trust Policy contains dts.aliyuncs.com.

         

     • If the AliyunDTSDefaultRole role does not meet the conditions, the authorization has failed. You must reauthorize the role. You can delete the AliyunDTSDefaultRole role and grant the permissions again.

  Fast authorization

  Using your Alibaba Cloud account (primary account), go to the fast authorization page for AliyunDTSDefaultRole. On the RAM quick authorization page, click Submit.

  Note

  • If the message Cloud resource access authorization successful! appears, the authorization is complete.

  • For more authorization methods, see Grant DTS permissions to access cloud resources.

Step 1: Migrate from PolarDB

This operation creates a new PolarDB cluster with the same data as the source PolarDB cluster. Incremental data from the source cluster is synchronized to the new PolarDB cluster in real time.

1. Log on to the PolarDB console and click Create Cluster.

2. For Billing Method, select Subscription or Pay-As-You-Go.

   • Subscription: You pay for compute nodes when you create the cluster. Storage space is billed hourly based on actual data volume.

   • Pay-As-You-Go: You do not need to pay upfront. Both compute nodes and storage space (billed based on the actual data volume) are billed hourly.

3. Configure the following parameters.

   Note

   For information about parameters not described in the following table, see Create a cluster.

   Parameter	Description
   Region	Select the region where the source PolarDB for PostgreSQL cluster is located.
   Creation Method	Select Migrate from PolarDB for upgrade.
   Source PolarDB Version	Select the version of the source PolarDB for PostgreSQL cluster.
   Source PolarDB Cluster	Select the source PolarDB for PostgreSQL cluster.
   Database Engine	Select the database engine version for the target cluster.
   Service Edition	Select the product version for the target cluster.
   CPU Architecture	Select the CPU architecture for the target cluster.
   Nodes	We recommend matching the number of nodes in the source cluster.
   Current Node Specifications	We recommend matching the node specifications of the source cluster.

4. On the right side of the page, review the cluster configuration. Set the Subscription Duration (for subscription clusters), Quantity, and whether to enable Auto-renewal (for subscription clusters).

5. Read and select the checkbox to agree to the terms of service. Click Buy Now. For subscription clusters, confirm the order details and payment method on the Pay page, and then click Purchase.

   Note

   • After the payment is successful, wait 10 to 15 minutes for the cluster to be created. You can then view the new cluster in the Clusters list.

   • If a cluster node has a status of Creating, the cluster is not yet ready. The cluster is available only when its status changes to Running.

   • Make sure that you have selected the correct region. Otherwise, you cannot view the cluster that you created.

6. After the cluster is created, click the cluster ID to go to the Basic Information page.

7. On the Basic Information page, in the PolarDB Upgrade section, confirm that the Replication Latency of the target PolarDB cluster is less than 60 seconds before you proceed.

   Note

   • You cannot perform a major version upgrade on a cluster that has DTS bidirectional synchronization enabled, as this may cause data inconsistency issues.

   • After the cluster is created, data synchronization from the source PolarDB cluster begins. You must complete the migration within 30 days. After 30 days, the upgrade feature is automatically disabled.

   • If the migration status changes to Precheck Failed after the PolarDB cluster is created, resolve the issue based on the error message. For example:

     • If the source cluster contains tables without a primary key, duplicate data may appear in the target database after synchronization. You can either click Skip the Verification or add a primary key to the tables and then click Continue Migration. To cancel the migration, click Abandon Migration.

     • If the source cluster contains a trigger, duplicate data may appear in the target database after synchronization. Delete the trigger from the source cluster and then click Continue Migration. Alternatively, click Abandon Migration and manually create a migration task in the DTS console. For more information, see How to configure a synchronization or migration job when the source database contains triggers.

Step 2: Add endpoints (optional)

A major version upgrade of PolarDB supports a switch with endpoint exchange. This allows you to keep the original database endpoint and switch to the new PolarDB cluster without changing any connection settings in your application. Note that an endpoint exchange is supported only for endpoints that exist on both the source PolarDB and target PolarDB clusters. By default, only the primary private endpoint and cluster private endpoint are created on the target cluster. If the source cluster has more than two endpoints, you must create the corresponding endpoints on the target cluster before the switch. Otherwise, those endpoints will not be switched. To learn how to create an endpoint for a PolarDB cluster, see View or apply for an endpoint.

Step 3: Switch over

You can perform the switchover when the replication latency of the target PolarDB cluster is less than 60 seconds.

1. On the Basic Information page, in the PolarDB Upgrade section, click Switch Over.

   Note

   • The upgrade typically completes within 5 minutes.

   • This operation swaps the read/write statuses of the source PolarDB cluster and the target PolarDB cluster, making the source PolarDB cluster read-only and the target PolarDB cluster read/write. Simultaneously, DTS reverses the data replication direction, which synchronizes new data from the target PolarDB cluster to the source PolarDB cluster.

2. In the dialog box that appears, select Switch with Endpoints (Connection Changes Not Required) or Switch without Endpoints (Connection Changes Required).

   • If you select Switch with Endpoints (Connection Changes Not Required), follow these steps:

     1. Select Switch with Endpoints (Connection Changes Not Required). The system automatically exchanges the endpoints of the source PolarDB and target PolarDB clusters. Your application will automatically connect to the target PolarDB cluster without any configuration changes.

        Important

        Before you select Switch with Endpoints (Connection Changes Not Required), make sure to read Notes on switching with endpoint exchange.

     2. Click OK.

   • If you select Switch without Endpoints (Connection Changes Required), follow these steps:

     1. Select Switch without Endpoints (Connection Changes Required).

     2. Click OK.

     3. Refresh the page. After the PolarDB Read/Write Status of the target PolarDB cluster changes to Read/Write, immediately update the database endpoint in your application.

Step 4: Complete the migration

After you complete Step 1: Migrate from PolarDB for an upgrade, you must complete the upgrade within 30 days.

1. On the Basic Information page, in the PolarDB Upgrade section, click Complete Migration.

2. In the Complete Migration dialog box, you can choose whether to Set the wal_level parameter to the default value replica, and then click OK.

   Note

   • Changing the wal_level parameter to its default value replica provides a minor improvement in write performance. However, resetting the wal_level parameter causes the PolarDB cluster to automatically restart to apply the new configuration.

   • After clicking OK, the system severs the synchronization link within two minutes, and the upgrade status changes to Disable Synchronization.

   • If you chose to change the wal_level, the PolarDB cluster automatically restarts to apply the new configuration.

   • If you no longer need the source PolarDB cluster, you can release the source PolarDB cluster.

Appendix: View data synchronization task details

During a major version upgrade that uses the logical migration method (DTS data synchronization), if you encounter a migration error, such as a failed precheck, or other issues, such as an unusually high replication latency, you can go to the details page of the corresponding DTS data synchronization task for more information.

1. On the Basic Information page, in the PolarDB Upgrade section, click the task name under DTS Data Synchronization Task to go to the data synchronization task list in the DTS console.

2. Find the corresponding data synchronization task. You can view precheck failure details, synchronization task details, synchronization task logs, and more.

3. (Optional) During the migration, if you need to adjust the synchronized objects, for example, to include a new database that was added to the source cluster, you can click Reselect Objects to reconfigure them.

Appendix: Migration rollback

Before you complete the migration, if you encounter issues such as data anomalies, you can perform a rollback to quickly restore the pre-migration state. A rollback makes the source cluster read/write, sets the target cluster to read-only, and reverses data synchronization from the target to the source cluster.

1. On the Basic Information page, in the PolarDB Upgrade section, click Roll Back Migration.

2. In the dialog box that appears, select Switch Back with Endpoints (Connection Changes Not Required) or Switch Back without Endpoints (Connection Changes Required).

   • If you select Switch Back with Endpoints (Connection Changes Not Required), follow these steps:

     1. Select Switch Back with Endpoints (Connection Changes Not Required). The system automatically exchanges the endpoints on the source and target clusters. Your application will automatically switch back to the source cluster without any configuration changes.

     2. Click OK. The source cluster becomes read/write, the target cluster becomes read-only, and data from the target cluster is synchronized to the source cluster.

   • If you select Switch Back without Endpoints (Connection Changes Required), follow these steps:

     1. Select Switch Back without Endpoints (Connection Changes Required). After the rollback is complete, you must update the database endpoint in your application as soon as possible.

     2. Click OK. The source cluster becomes read/write, the target cluster becomes read-only, and data from the target cluster is synchronized to the source cluster.

     3. Refresh the page. When the Source RDS Read/Write Status changes to Read/Write, update the database endpoint in your application to the source cluster endpoint as soon as possible.

Appendix: Cancel migration

If you no longer wish to proceed with the major version upgrade, you can cancel the migration. This action severs the synchronization link, disassociating the source and target clusters.

1. On the Basic Information page, in the PolarDB Upgrade section, click Cancel Migration.

2. In the Cancel Migration dialog box, you can choose whether to Set the wal_level parameter to the default value replica, and then click OK.

FAQ