PolarDB:Procedure

Preparations

Check whether the service-linked role for PolarDB is created

Before you perform an upgrade, make sure that the service-linked role for PolarDB has been created and that Data Transmission Service (DTS) has been authorized to access Alibaba Cloud resources. For more information, see Authorize DTS to access Alibaba Cloud resources.

The following section describes how to check whether the service-linked role for PolarDB has been created.

1. Log on to the Resource Access Management (RAM) console.

2. In the left-side navigation pane, choose Identities > Roles.

3. Check whether a service-linked role named AliyunServiceRoleForPolarDB already exists in the list.

   • If the service-linked role exists in the list, perform the operations in Step 1: Select the Upgrade/Migrate from PolarDB method to create a destination PolarDB cluster.

   • If the service-linked role does not exist in the list, continue with the following steps.

4. Click Create Role.

5. In the Select Role Type step of the Create Role panel, select Alibaba Cloud Service and then click Next.

6. In the Configure Role step, set Role Type to Service Linked Role and select ApsaraDB for PolarDB from the Select Service drop-down list.

7. Click OK. In the Roles list, confirm that the role is created.

Remove extra system accounts from the source PolarDB for MySQL cluster

To prevent the system account of the destination PolarDB for MySQL cluster from being overwritten during migration, make sure that the root and aliyun_root accounts do not exist in the source PolarDB for MySQL cluster at the same time. Before you initiate the migration process, we recommend that you remove extra system accounts from the source PolarDB for MySQL cluster.

The following table lists the correct system account name for each version of PolarDB for MySQL.

Apart from the corresponding system account for each version mentioned in the preceding table, all other system accounts must be removed.

The following example shows how to remove extra system accounts from a PolarDB for MySQL 5.6 cluster:

1. Use a privileged account to connect to the cluster. For more information, see Connect to a cluster.

2. Find all root and aliyun_root system accounts.

   select * from mysql.user where user in ('root', 'aliyun_root');

3. Remove extra system accounts. The correct system account of the PolarDB for MySQL 5.6 cluster is root. Therefore, you must remove the aliyun_root account.

   delete from mysql.user where user = 'aliyun_root' limit n; 

(Optional) Perform intelligent stress testing

Before you perform a PolarDB major version upgrade, you can use the intelligent stress testing feature to simulate your business traffic running in a PolarDB cluster of the destination version. This helps you achieve the following goals:

• Check whether the specifications of your cluster need to be scaled to effectively handle business traffic peaks.

• Compare the execution performance of SQL templates between PolarDB clusters of the original version and the destination version.

For information about how to perform an intelligent stress testing task, see Intelligent stress testing.

Step 1: Select the Upgrade/Migrate from PolarDB method to create a destination PolarDB cluster

In this step, create a cluster that contains the same data as your source PolarDB for MySQL cluster. The incremental data of the source PolarDB for MySQL cluster is synchronized to the new cluster in real time.

1. Log on to the PolarDB console.

2. Go to the PolarDB cluster buy page by using one of the following methods:

   • On the Clusters page, click Create Cluster.

   • On the Clusters page, click the ID of the cluster that you want to upgrade. In the left-side navigation pane of the page that appears, choose Settings and Management > Version Management. On the Major Version Upgrade tab, click Upgrade by Migration.

3. Set Billing Method to Subscription, Pay-as-you-go, or Serverless.

   • Subscription: You must pay upfront for compute nodes when you create a cluster. Storage is billed based on actual hourly usage, and fees are deducted from your account on an hourly basis.

   • Pay-as-you-go: An upfront payment is not required. You are charged fees for the compute nodes and the amount of storage that is consumed by your data. These fees are deducted from your account balance on an hourly basis.

   • Serverless: An upfront payment is not required. Resources such as compute nodes, storage space, and PolarProxy dynamically scales based on the actual demand. You are charged fees based on the actual usage of these scaled resources.

4. Configure the parameters on the page. The following table describes the parameters.

   Note

   For information about the parameters that are not described in the following table, see Purchase clusters.

   Parameter	Description
   Creation Method	Select Upgrade/Migrate from PolarDB.
   Region	The region of the source PolarDB for MySQL cluster.
   Source PolarDB Version	The engine version of the source PolarDB for MySQL cluster. Valid values: 5.6, 5.7, and 8.0.
   Source PolarDB Cluster	The ID of the source PolarDB for MySQL cluster.
   Database Engine	The engine version of the destination PolarDB cluster. Note If you want to perform a version upgrade, you can choose a version that is the same as or different from the source PolarDB cluster. If you want to perform an edition upgrade, you can only choose MySQL 8.0.
   Database Edition	The Database Edition is the same as that of the original cluster. You do not need to configure this parameter.
   Edition	The edition of the destination PolarDB cluster. Note If you want to perform a version upgrade, set the parameter to Cluster Edition (Recommended). If you want to perform an edition upgrade, set the parameter to Multi-master Cluster (Database/Table).
   CPU Architecture	The CPU architecture of the cluster is the same as that of the original cluster. You do not need to configure this parameter.
   Nodes	The number of nodes is the same as that of the original cluster. You do not need to configure this parameter.
   Current Specification	The selected specification of the destination cluster.
   PolarProxy Type	The PolarProxy type of the cluster is the same as that of the original cluster. You do not need to configure this parameter.

5. In the upper-right corner of the page, check the cluster configurations and configure the Duration, Quantity, and Auto-renewal parameters. The Duration parameter is available only for subscription clusters.

6. Read and select the terms of service. Click Buy Now.

7. On the Purchase page, confirm the order and the payment method, and click Purchase.

   Note

   • After you complete the payment, wait 10 to 15 minutes. Then, you can view the newly created cluster on the Clusters page.

   • If specific nodes in the cluster are in the Creating state, the cluster is still being created and is unavailable. The cluster is available only when the cluster is in the Running state.

   • Make sure that you have selected the region in which the cluster is deployed. Otherwise, you cannot view the cluster.

8. Click the cluster ID to go to the Basic Information page of the cluster.

9. In the PolarDB Upgrade section of the Basic Information page, view the value of the Replication Delay parameter for the destination PolarDB cluster. If the value of the parameter is less than 60 seconds, perform upgrade operations.

   Note

   • Do not upgrade a cluster that has a two-way DTS data synchronization task in progress. Data inconsistency may occur.

   • After the destination cluster is created, the DTS task starts synchronizing data from the source PolarDB cluster to the destination PolarDB cluster. You must complete the upgrade within 30 days. The upgrade is disabled after the 30-day period.

   • You can also click Cancel Upgrade. For information about the impact of cancelling an upgrade, see FAQ of major version upgrades.

   • If the status is Precheck Failed, perform troubleshooting based on the error message.

     For example, if a trigger has been created in the source PolarDB cluster, the precheck fails. Delete the trigger in the source PolarDB cluster, and then click Continue Upgrade. Alternatively, you can click Cancel Upgrade and then manually create a migration task in the DTS console. For more information, see Configure a data synchronization or migration task for a source database that contains a trigger.

   • During an edition upgrade, the primary node whose ID is 1 is used to process write requests by default. To prevent errors during data synchronization, we recommend that you do not change the primary node before the upgrade is complete.

(Optional) Step 2: Add endpoints

Endpoints of the source and destination PolarDB clusters can be exchanged during the service switchover process of a major version upgrade. This way, you can connect to the destination PolarDB cluster without the need to modify the connection configurations of your application after the switchover. You can interchange endpoints only if both the source and destination PolarDB cluster have the endpoints. By default, the destination PolarDB cluster has only a private primary endpoint and a private cluster endpoint. If the source PolarDB cluster has more endpoints, you must create the corresponding endpoints for the destination PolarDB cluster before the switchover if you want to interchange the endpoints. For information about how to create an endpoint for a PolarDB cluster, see Manage endpoints.

Step 3: Switch over services

Before you switch over services to the destination PolarDB cluster, make sure that the replication latency of the destination PolarDB cluster is less than 60 seconds.

1. Log on to the PolarDB console.

2. Find the destination PolarDB cluster and click the cluster ID.

3. In the PolarDB Upgrade section of the Basic Information page, click Upgrade Switchover.

   Note

   • In most cases, the switchover is completed within 5 minutes.

   • After the switchover, the source PolarDB cluster becomes read-only, while the destination PolarDB cluster processes both read and write requests. DTS also changes the data replication direction by synchronizing incremental data from the destination PolarDB cluster to the source PolarDB cluster.

4. In the dialog box that appears, select Switch with Endpoints (Connection Changes Not Required) or Switch without Endpoints (Connection Changes Required) based on your business requirements.

   • If you want the endpoints of the source and destination PolarDB clusters to be exchanged during the service switchover process, perform the following steps:

     1. Select Switch with Endpoints (Connection Changes Not Required). The system automatically interchanges the endpoints of the source and destination PolarDB clusters during the switchover process. After the switchover, you can connect to the destination PolarDB cluster without the need to change the connection configurations of your application.

        Important

        • Before you select Switch with Endpoints (Connection Changes Not Required), make sure that you read notes for switchover with endpoints.

        • If the source PolarDB cluster is the source or destination of existing DTS tasks, you must change the source or destination cluster of the DTS tasks to the destination PolarDB cluster. Such tasks include data synchronization tasks, data migration tasks, and change tracking tasks. For more information, see Switch over DTS tasks.

     2. Click OK.

   • If you do not want to the endpoints of the source and destination PolarDB clusters to be exchanged during the service switchover process, perform the following steps:

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

     2. Click OK.

     3. Refresh the page. If Read/Write Status of Destination PolarDB changes to Read and Write, change the database endpoint in your applications at the earliest opportunity.

(Optional) Step 4: Switch over DTS tasks

1. Log on to the PolarDB console.

2. Find the destination PolarDB cluster and click the cluster ID.

3. In the PolarDB Upgrade section of the Basic Information page, click Business DTS Task Database Endpoint Switchover.

   

4. In the Business DTS Task Database Endpoint Switchover dialog box, select Source Instance DTS Task (Forward Switchover) or Destination Instance DTS Task (Switchover Rollback).

   Important

   Before the switchover, check the states of DTS synchronization tasks of the source and destination PolarDB clusters. For more information, see DescribeDtsJobDetail.

   

   • To switch over DTS tasks from the source PolarDB cluster to the destination PolarDB cluster, perform the following steps:

     1. Select the DTS tasks of the source PolarDB cluster.

     2. Click Commit Forward Switchover.

   • To switch over DTS tasks from the destination PolarDB cluster to the source PolarDB cluster, perform the following steps:

     

     1. Select the DTS tasks of the destination PolarDB cluster.

     2. Click Commit Switchover Rollback.

Step 5: Complete the upgrade

After you complete the operations in Step 1: Select the Upgrade/Migrate from PolarDB method to create a destination PolarDB cluster, you must complete the upgrade within 30 days.

1. Log on to the PolarDB console.

2. Find the destination PolarDB cluster and click the cluster ID.

3. In the PolarDB Upgrade section of the Basic Information page, click Complete Upgrade.

4. In the dialog box that appears, specify whether you want to disable binary logging for the destination cluster. Then, click OK.

   Note

   • After you click OK, the system stops data synchronization within about 2 minutes. During this process, the upgrade status of the cluster is Disabling Synchronization.

   • If you disable binary logging for the destination cluster, the PolarDB cluster is restarted for the configuration to take effect.

   • If you no longer require the source PolarDB cluster, you can release the cluster. For information about how to release a cluster, see Release a cluster.

   • If you are performing an edition upgrade, the system randomly assigns primary nodes for processing write requests after you click OK in the Complete Upgrade dialog box.

(Optional) View the details of data synchronization tasks

If an error occurs during an upgrade, you can go to the DTS synchronization task details page for more information.

1. Log on to the PolarDB console.

2. Find the destination PolarDB cluster and click the cluster ID.

3. In the PolarDB Upgrade section of the Basic Information page, click the name of the DTS Data Synchronization Task to go to the synchronization task list in the DTS console.

4. Click the ID of the synchronization task to go to the task details page.

5. During an upgrade, if you want to change the objects that you want to synchronize, you can click Reselect Objects on the task details page. For example, the source PolarDB cluster may have new databases that also need to be included in the synchronization task.

(Optional) Roll back the upgrade

If an error occurs before you complete the upgrade, you can roll back the upgrade. After the rollback, the source PolarDB cluster processes both read and write requests, while the destination PolarDB cluster becomes read-only. DTS also changes the data replication direction by synchronizing incremental data from the source PolarDB cluster to the destination PolarDB cluster. If you need to proceed with the major version upgrade after the rollback, you can perform the operations described in Step 3: Switch over services.

1. Log on to the PolarDB console.

2. Find the destination PolarDB cluster and click the cluster ID.

3. In the PolarDB Upgrade section of the Basic Information page, click Upgrade Rollback.

4. In the dialog box that appears, select Switch Back with Endpoints (Connection Changes Not Required) or Switch Back without Endpoints (Connection Changes Required) based on your business requirements.

   • If you want the endpoints to be switched back during the upgrade rollback, perform the following steps:

     1. Select Switch Back with Endpoints (Connection Changes Not Required). The system automatically switches back the endpoints of the source and destination PolarDB clusters during the upgrade rollback process. This way, you can connect to the source PolarDB cluster without the need to change the connection configurations of your application after the rollback.

     2. Click OK.

        After the rollback, the source PolarDB cluster processes both read and write requests, while the destination PolarDB cluster becomes read-only. DTS also changes the data replication direction by synchronizing incremental data from the source PolarDB cluster to the destination PolarDB cluster.

        Note

        When you roll back an edition upgrade, you can select the endpoints for the rollback.

   • If you do not want the endpoints to be switched back during the upgrade rollback, perform the following steps::

     1. Select Switch Back without Endpoints (Connection Changes Required). This way, you need to change the database endpoint in your application at the earliest opportunity after the switchover.

     2. Click OK. After the rollback, the source PolarDB cluster processes both read and write requests, while the destination PolarDB cluster becomes read-only. DTS will also change the data replication direction. Incremental data is synchronized from the source PolarDB cluster to the destination PolarDB cluster.

     3. Refresh the page. If the value of the Read/Write Status of Source PolarDB parameter changes to Read and Write, change the database endpoint in your applications at the earliest opportunity.

(Optional) Cancel the upgrade

1. Log on to the PolarDB console.

2. Find the destination PolarDB cluster and click the cluster ID.

3. In the PolarDB Upgrade section of the Basic Information page, click Cancel Upgrade.

4. In the Cancel Upgrade dialog box, click OK.