PolarDB：Procedure

Preparations

Check whether the service-linked role for PolarDB is created (required only for logical migration)

Before you use the logical migration (data synchronization over DTS) method to perform an upgrade, check whether the service-linked role for PolarDB has been created and whether Data Transmission Service (DTS) has been authorized to access Alibaba Cloud resources. For more information, see Authorize DTS to access Alibaba Cloud resources. To check whether the service-linked role for PolarDB has been created, perform the following steps:

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

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

   

3. If the service-linked role exists in the list, perform the operations in Step 1: Select the Migrate from RDS method to create a destination PolarDB cluster. If the service-linked role does not exist in the list, you must create the role.

4. In the upper-left corner, click Create Role.

5. In the Select Role Type step of the Create Role panel, select Alibaba Cloud Service and 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. Return back to the role list to confirm that the role is created.

Remove extra system accounts from the source ApsaraDB RDS instance (required only for logical migration)

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

The following table lists the correct system account name for each version of ApsaraDB RDS 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 an ApsaraDB RDS for MySQL 5.6 instance:

1. Use a privileged account to connect to the database.

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 name of ApsaraDB RDS for MySQL 5.6 is root. Therefore, you must remove the aliyun_root account.

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

(Optional) Check the whitelist configurations

If the whitelist configurations of the primary RDS instance and read-only RDS instance are different, you need to merge the whitelist configurations of the read-only RDS instance into those of the primary RDS instance. This ensures that the whitelist configurations of the read-only RDS instance are automatically synchronized to the destination PolarDB cluster.

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

In this step, create a PolarDB cluster that contains the same data as the source ApsaraDB RDS for MySQL instance. Incremental data is synchronized from the source ApsaraDB RDS for MySQL instance to the PolarDB cluster in real time.

1. Log on to the PolarDB console. In the left-navigation page, click Clusters. On the Clusters page, click Create Cluster to go to the PolarDB buy page.

2. 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 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.

3. Configure the parameters. 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 Migrate from RDS. Note The PolarDB cluster is in read-only mode before the migration and switchover. By default, binary logging is enabled for the cluster.
   Region	The region where the source ApsaraDB RDS for MySQL instance is deployed. Note The destination PolarDB cluster must be also deployed in this region.
   RDS Engine Type	The database engine of the source ApsaraDB RDS instance. The default value of this parameter is MySQL and cannot be changed.
   RDS Engine Version	The database engine version of the source ApsaraDB RDS for MySQL instance. Valid values: 5.6, 5.7, and 8.0.
   Source RDS Instance	The source ApsaraDB RDS for MySQL instance. The available source ApsaraDB RDS for MySQL instances exclude read-only instances.
   Database Engine	The database engine version of the destination PolarDB cluster. You can select the same version as the source ApsaraDB RDS for MySQL instance or a different version.
   Node Specification	The node specifications of the cluster. You can specify node specifications based on your business requirements. We recommend that you select specifications that are the same as or higher than the specifications of the source ApsaraDB RDS for MySQL instance. For more information about PolarDB node specifications, see Compute node specifications of PolarDB for MySQL Enterprise Edition.
   Storage Engine	PolarDB supports the following storage engines: InnoDB and InnoDB & X-Engine. InnoDB: InnoDB storage engine. InnoDB & X-Engine: deploys both InnoDB and X-Engine. If you select this option, you can specify the X-Engine memory usage ratio. For more information, see X-Engine Edition.

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

5. Read and select terms of service. Click Buy Now.

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

   Note

   • After you complete the payment, wait for 10 to 15 minutes. Then, you can view the new 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 select the region where the cluster is deployed. Otherwise, you cannot view the cluster.

7. After the cluster is created, log on to the PolarDB console and click the cluster ID to go to the Basic Information page of the cluster.

8. In the RDS Migration section of the Basic Information page, check the Replication Latency value of the destination PolarDB cluster. If the value is smaller than 60 seconds, you can perform the operations in Step 3: Switch over services.

   

   Note

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

   • After the cluster is created, the system starts migrating data from the source ApsaraDB RDS for MySQL instance to the cluster. You must perform the operations in Step 5: Complete the migration within 30 days after the cluster is created. Otherwise, the migration task is automatically disabled after the 30-day period.

   • If the logical migration method is used and the Status value displayed in the RDS Migration section is Precheck Failed after the PolarDB cluster is created, follow the instructions in the error message to troubleshoot the issue.

     For example, if a trigger is created in the source ApsaraDB RDS for MySQL instance, the precheck fails and the "The RDS instance has a trigger." error message is reported. You can delete the trigger and then click Continue Migration. Alternatively, you can click Cancel Migration and then manually create a data synchronization task in the DTS console. For more information, see Configure a data synchronization task for a source database that contains a trigger.

   • You can click Cancel Migration in this step. For information about the impacts, see FAQ.

(Optional) Step 2: Add endpoints

You can select the Switch with Endpoints (Connection Changes Not Required) option when you switch over services from the source ApsaraDB RDS for MySQL instance to the destination PolarDB cluster. This way, the endpoints between the source ApsaraDB RDS for MySQL instance and the destination PolarDB cluster are automatically interchanged during the switchover. After the switchover, you can connect to the destination PolarDB cluster without the need to modify the connection configurations of your application. You can interchange endpoints only if the source ApsaraDB RDS for MySQL instance and the 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 ApsaraDB RDS for MySQL instance has more endpoints, you must create the corresponding endpoints for the destination PolarDB cluster if you want to interchange the endpoints. For information about how to create endpoints for a PolarDB cluster, see Manage endpoints. For information about how to create endpoints for an ApsaraDB RDS for MySQL instance, see Configure endpoints for an RDS instance.

Step 3: Switch over services

If the Replication Latency value of the destination PolarDB cluster is smaller than 60 seconds, you can perform the switchover operation.

1. Log on to the PolarDB console.

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

3. In the RDS Migration section of the Basic Information page, click Switch Over Business.

   

   Note

   • In most cases, 5 minutes are required for the system to compete the switchover.

   • After the switchover, the read/write status of the source ApsaraDB RDS for MySQL instance and the destination PolarDB cluster are interchanged. The read/write status of the source ApsaraDB RDS for MySQL instance is changed to Read-only, and the read/write status of the PolarDB cluster is changed to Read and Write. The replication direction is also changed. In this case, incremental data is synchronized from the PolarDB cluster to the ApsaraDB RDS for MySQL instance.

4. To continue the migration, click OK. To check non-upgrade DTS tasks, click Cancel.

   

5. In the Switches the business over to the new database dialog box, select Switch with Endpoints (Connection Changes Not Required) or Switch without Endpoints (Connection Changes Required).

   

   • If you want the endpoints of the source ApsaraDB RDS for MySQL instance and the destination PolarDB cluster to be interchanged during the switchover, perform the following steps:

     1. Select Switch with Endpoints (Connection Changes Not Required). The system interchanges the endpoints between the ApsaraDB RDS for MySQL instance and the PolarDB cluster during the switchover. After the switchover, you do not need to modify the configurations of your application to connect to the PolarDB cluster.

        Important

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

        • If the source ApsaraDB RDS for MySQL instance 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 after the upgrade. Such tasks include data synchronization tasks, data migration tasks, and change tracking tasks. For more information, see Step 4: Switch over DTS tasks.

     2. Click OK.

   • If you do not want the endpoints of the source ApsaraDB RDS for MySQL instance and the destination PolarDB cluster to be interchanged during the switchover, perform the following steps:

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

     2. Click OK.

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

   Note

   • If data errors occur after the switchover is complete, you can roll back the switchover. This allows you to restore the database and data to the original state before the switchover is performed. For more information, see Roll back the migration. You can then select Cancel Migration to restore the status before the migration.

(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 RDS Migration 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 status of the DTS synchronization tasks of the source ApsaraDB RDS for MySQL instance and the destination PolarDB cluster. For more information, see DescribeDtsJobDetail.

   

   • To select Source Instance DTS Task (Forward Switchover), perform the following steps:

     1. Select the DTS task of the source ApsaraDB RDS for MySQL instance.

     2. Click Commit Forward Switchover.

   • To select Destination Instance DTS Task (Switchover Rollback), perform the following steps:

     

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

     2. Click Commit Switchover Rollback.

Step 5: Complete the migration

1. Log on to the PolarDB console.

2. Find the cluster and click the cluster ID.

3. In the RDS Migration section of the Basic Information page, click Complete Migration. In the dialog box that appears, click OK.

   Note

   • After you click OK, the system stops data synchronization within approximately 2 minutes. During this process, the migration status is Disable Synchronization. Wait until the migration is complete.

   • In the Complete Migration dialog box, you can specify whether to disable the binary logging feature for the PolarDB cluster. If you disable the binary logging feature, write performance can be slightly improved. The PolarDB cluster automatically restarts after you disable the binary logging feature for the new configuration to take effect.

   • If you no longer need the source ApsaraDB RDS instance, you can release or unsubscribe from the instance. For more information, see the "(Optional) Release or unsubscribe from an ApsaraDB RDS instance" section of this topic.

   • If you want to perform operations such as renewal or configuration changes on the source ApsaraDB RDS instance, click Complete Migration first.

(Optional) Release or unsubscribe from an ApsaraDB RDS instance

After data is migrated from the source ApsaraDB RDS instance to the PolarDB cluster, you can release or unsubscribe from the instance if services run on the cluster as expected and the instance is no longer required.

• You can unsubscribe from ApsaraDB RDS instances that use the subscription billing method. For more information, see Unsubscribe from a subscription primary RDS instance.

• Release ApsaraDB RDS instances that use the pay-as-you-go billing method at the earliest opportunity to save RDS resources. For more information, see Release or unsubscribe from an ApsaraDB RDS for MySQL instance.

(Optional) View the details of a data synchronization task (available only for logical migration)

During the process of upgrade by using logical migration, if you encounter migration errors (such as a precheck failure) or other exceptions (such as high replication delay), you can go to the details page of the data synchronization task to view specific information about the task.

1. Log on to the PolarDB console.

2. Find the cluster and click its ID.

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

   

4. Find the data synchronization task. You can view precheck failure details, data synchronization task details, and data synchronization task logs.

   

5. During the migration process, if you want to adjust the synchronization objects of the synchronization task, you can click Reselect Objects. For example, the source ApsaraDB RDS for MySQL instance may have new databases that also need to be included in the synchronization task.