All Products
Search

This Product

    PolarDB:Upgrade steps

    Document Center

    PolarDB:Upgrade steps

    Last Updated:Jun 21, 2026

    When you upgrade an ApsaraDB RDS for MySQL instance to a PolarDB for MySQL cluster with one click, the process creates a target PolarDB cluster and synchronizes data to it. The upgraded PolarDB cluster inherits the accounts, databases, IP address whitelist, and necessary parameter configurations from the source RDS instance.

    The upgrade process includes the following steps:

    Note

    • The one-click upgrade feature supports two methods: physical migration (physical replication) and logical migration (data synchronization by using Data Transmission Service (DTS)). For more information, see Comparison between physical migration and logical migration.

      • physical migration (physical replication): Use this method to migrate high-availability ApsaraDB RDS for MySQL 5.6 and 5.7 instances that use local SSD to a PolarDB for MySQL cluster of the same version.

      • logical migration (data synchronization by using DTS): This method applies to all other types of ApsaraDB RDS for MySQL instances. You can migrate them to a PolarDB for MySQL cluster of the same or a different version.

    • For detailed instructions, refer to the individual steps.

    1. Prerequisites:

    2. Step 1: Migrate from RDS: On the PolarDB purchase page, set Creation Method to Migrate from RDS, and then specify the source RDS version and instance to create a target PolarDB cluster.

    3. (Optional) Step 2: Add endpoints: The one-click upgrade supports a switchover with endpoint exchange. This allows you to retain the original endpoints of the source RDS instance. Your applications can switch to the target PolarDB cluster without any configuration changes. Note that you can exchange endpoints only if they exist on both the source RDS instance and the target PolarDB cluster.

    4. Step 3: Switch over: Exchange the read/write status of the source RDS instance and the target PolarDB cluster. This operation sets the source RDS instance to Read Only and the target PolarDB cluster to read and write. The replication direction is also reversed, synchronizing new data from the target PolarDB cluster back to the source RDS instance.

    5. (Optional) Step 4: Switch over the DTS task of the source instance: If the source instance has an associated DTS task that is not part of the one-click migration, you can use this feature to modify the source or destination of the DTS synchronization or migration task for a smooth business cutover.

    6. Step 5: Complete the migration: When the business data migration is complete and you no longer need data synchronization, you can finalize the entire upgrade process.

    7. (Optional) Unsubscribe from or release the RDS instance: If your business is running stably on the PolarDB cluster and the source RDS instance is no longer needed, you can unsubscribe from or release it.

    After the switchover, if you find data inconsistencies or other issues, you can perform a migration rollback to quickly restore the state before the upgrade. You can then choose to cancel the migration to revert to the state before the switchover.

    Prerequisites

    Check PolarDB service-linked role (for logical migration only)

    Note

    If you have completed the migration evaluation and no exceptions were reported, you can skip this check.

    Before you perform a one-click upgrade by using logical migration (data synchronization by using Data Transmission Service (DTS)), check whether a service-linked role for PolarDB has been created and whether DTS has been granted permissions to access cloud resources.

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

      1. Use your Alibaba Cloud account (main account) to go to the Identity Management > Role list in the RAM console.

      2. Check whether a service-linked role named AliyunServiceRoleForPolarDB exists. In the search box, enter AliyunServiceRoleForPolarDB to verify that the role is in the list.

        • 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, set Trusted Cloud Service to AliyunServiceRoleForPolarDB, and then click Create Service-linked Role.

    • Check whether permissions have been granted to DTS to access cloud resources

      This section explains how to check the authorization result and how to grant permissions quickly. For more information, see Grant DTS permissions to access cloud resources.

      Authorization result

      1. Use your Alibaba Cloud account (main account) to go to the RAM console and navigate to the Identity Management > Role list.

      2. Check whether a role named AliyunDTSDefaultRole exists. In the search box, enter AliyunDTSDefaultRole to verify that the role is in the list.

        1. If it does not exist, go to Quick 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.

        • If the AliyunDTSDefaultRole role meets the following conditions, the authorization is successful.

          • Permission management includes the system policy AliyunDTSRolePolicy.

          • The Trust Policy contains dts.aliyuncs.com.

            This means that in the trust policy JSON, the Service field of Principal contains dts.aliyuncs.com, Action is sts:AssumeRole, and Effect is Allow.

        • If the AliyunDTSDefaultRole role does not meet the preceding conditions, the authorization failed. You must grant the permissions again. You can delete the AliyunDTSDefaultRole role and then re-authorize it.

      Quick authorization

      Use your Alibaba Cloud account (primary account) to visit the AliyunDTSDefaultRole quick authorization page. On the quick authorization page, click Submit.

      Note

    Delete extra system accounts (for logical migration only)

    Note

    If you have completed the migration evaluation and no exceptions were reported, you can skip this check.

    To ensure system account compatibility between ApsaraDB RDS for MySQL and PolarDB and to prevent system accounts on the target PolarDB cluster from being overwritten, the source RDS instance cannot have both root and aliyun_root accounts at the same time. Therefore, delete any extra system accounts from the source RDS instance before you start the upgrade.

    The following table lists the correct system account names for different versions of ApsaraDB RDS for MySQL:

    RDS for MySQL version

    System account name

    ApsaraDB RDS for MySQL 5.6

    root

    ApsaraDB RDS for MySQL 5.7

    aliyun_root

    ApsaraDB RDS for MySQL 8.0

    aliyun_root

    For each version, you must delete all system accounts other than the correct one. For example, the correct system account for an ApsaraDB RDS for MySQL 5.7 instance is aliyun_root. If you manually created a root account in the console, you must delete it. Before you delete the account, make sure that it is not used by your business.

    Note

    System accounts may be created by you or by the system and left over from a version upgrade. In some cases, these accounts may not be visible in the console.

    Example

    The following steps show how to clean up extra system accounts from an ApsaraDB RDS for MySQL 5.6 instance:

    1. Connect to the instance by using a privileged account.

    2. Find all root and aliyun_root system accounts.

      SELECT * FROM mysql.user WHERE `user` IN ('root', 'aliyun_root');

    3. Delete the extra system accounts. The correct system account for ApsaraDB RDS for MySQL 5.6 is root. Therefore, you must delete the aliyun_root account.

      DELETE FROM mysql.user WHERE `user` = 'aliyun_root' LIMIT n;

    (Optional) Check IP address whitelist

    If the IP address whitelists of the source primary and read-only instances are different, you must merge the whitelists of the read-only instances into the whitelist of the primary instance in advance. This ensures that the whitelists of the read-only instances are automatically synchronized to the target PolarDB cluster.

    Step 1: Migrate from RDS

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

    Note

    • Before you start the migration, we recommend that you first complete the migration evaluation.

    • Before you start the migration, ensure that the PolarDB cluster has more storage space than the source RDS instance.

    • When you migrate data by using Data Transmission Service (DTS), the full data initialization phase consumes read and write resources on both the source and target databases. This may increase the database load. You can adjust the synchronization rate as needed. For detailed instructions, see Adjust the migration rate.

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

    2. Set Billing Method to Subscription, Pay-As-You-Go, or Serverless.

      • Subscription: You pay for the compute nodes when you create the cluster. The storage space is billed hourly based on the actual data volume, and charges are deducted from your account balance.

      • Pay-as-you-go: No upfront payment is required. Both the compute nodes and the storage space (based on actual data volume) are billed hourly, and charges are deducted from your account balance.

      • Serverless: No upfront payment is required. Resources such as compute nodes, storage space, and database proxy are dynamically and elastically scaled based on actual demand. You are billed for the actual usage of the scaled resources.

    3. Configure the following parameters.

      Note

      For parameters not detailed in the following table, refer to the relevant sections in Purchase a cluster.

      Parameter

      Description

      Creation Method

      Select Migrate from RDS.

      Note

      Before the final migration switchover, the PolarDB cluster is in a read-only state, and its binary log is enabled by default.

      Region

      Select the region where the source ApsaraDB RDS for MySQL instance is located.

      Note

      The new PolarDB cluster is created in this region.

      Source RDS Engine

      The engine type of the source RDS instance. This is fixed as MySQL and cannot be changed.

      Source RDS Version

      The version of the source RDS instance. You can select 5.6, 5.7, or 8.0.

      Source RDS Instance

      Select the source RDS primary instance.

      Compatibility

      The database engine version of the target PolarDB cluster. You can choose the same version as the source RDS instance or a different version.

      Node Specifications

      Select a specification as needed. We recommend that you select a specification equal to or higher than that of the source RDS instance. For more information about PolarDB node specifications, see Compute node specifications for Enterprise Edition.

      Storage engine

      You can select InnoDB or InnoDB & X-Engine.

      Note

      InnoDB & X-Engine: A hybrid engine deployment of InnoDB and X-Engine. If you select this option, you can set the proportion of storage for X-Engine. For more information, see X-Engine.

    4. In the upper-right corner, check the cluster configuration, set the Subscription Duration (for subscription clusters) and Quantity, and specify whether to enable Auto-renewal.

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

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

      Note

      • After the payment is successful, it takes 10 to 15 minutes to create the cluster. You can then find the new cluster in the Clusters list.

      • If the status of a node in the cluster is Creating, the cluster creation is not complete and the cluster is unavailable. The cluster is available only when its status changes to Running.

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

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

    8. In the RDS Migration section of the Basic Information page, confirm that the Replication Latency of the target PolarDB cluster is less than 60 seconds. You can then proceed to Step 3: Switch over.

      At this point, the Status is Synchronizing Data, the Source RDS Read/Write Status is read and write, and the PolarDB Read/Write Status is read-only.

      Note

      • You cannot migrate or upgrade instances that have an existing two-way DTS synchronization task by using the one-click feature. Otherwise, data inconsistency issues may occur.

      • After the cluster is created, data synchronization from the RDS instance begins. You must perform Step 5: Complete the migration within 30 days. Otherwise, the migration feature is automatically disabled.

      • If you are using logical migration (data synchronization by using DTS) and the RDS migration status changes to Pre-check failed after the PolarDB cluster is created, follow the instructions in the Error Message to resolve the issue.

        For example, if a trigger exists on the source RDS instance, the precheck fails and reports the "The RDS instance has a trigger" error. You must delete the trigger from the source RDS instance and then click Continue migrating. Alternatively, you can click Give up migration and manually create a migration task in the DTS console. For details, see How to configure a synchronization or migration task when the source database contains triggers.

      • You can choose to Give up migration at this step. For information about the impacts, see FAQ.

    (Optional) Step 2: Add endpoints

    PolarDB one-click migration supports a switchover with endpoint exchange, allowing you to retain the original database endpoints. Your applications can switch to PolarDB without any configuration changes. Note that you can exchange endpoints only if they exist on both the source RDS instance and the target PolarDB cluster. By default, only a private primary endpoint and a private cluster endpoint are created on the target. If the source has more than two endpoints, you must create the corresponding endpoints on the target before the switchover. Otherwise, they will not be switched. For information about how to create endpoints for PolarDB clusters and RDS instances, see Manage endpoints and Configure an endpoint.

    Note

    • You can add endpoints only after the target cluster is in the running state. You can also configure endpoint properties, instance parameters, and add read-only nodes based on your business needs.

    • To exchange private endpoints during a switchover, ensure that the source RDS instance and the target PolarDB cluster are in the same VPC. Otherwise, your original services will be unable to connect after the switchover.

    Step 3: Switch over

    When the Replication Latency of the target PolarDB cluster is less than 60 seconds, you can perform the switchover.

    1. Go to the PolarDB console.

    2. Find the target cluster and click its ID.

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

      The DTS data synchronization task displayed on the page is a free task. Do not modify this task manually. Otherwise, the migration will fail.

      Note

      • The switchover process typically takes less than 5 minutes.

      • This operation exchanges the read/write status of the source RDS instance and the target PolarDB cluster. The source RDS instance is set to Read-only, and the PolarDB cluster is set to read and write. The replication direction is also reversed, so new data from the PolarDB cluster is synchronized to the RDS instance.

    4. In the Switch Business to New Database dialog box, select Switch with Endpoints (No Application Configuration Change Required) or Switch without Endpoints (Application Needs to Be Reconfigured to New PolarDB Endpoint).

      • If you select Switch with Endpoints (No Application Configuration Change Required), follow these steps:

        1. Select Switch with Endpoints (No Application Configuration Change Required). The system automatically exchanges the endpoints of the source RDS instance and the target PolarDB cluster. You do not need to modify any configurations in your application to connect to the target PolarDB cluster.

          Important

          Before you select Switch with Endpoints (No Application Configuration Change Required), be sure to read Notes on switchover with endpoints.

        2. Click OK.

      • If you select Switch without Endpoints (Application Needs to Be Reconfigured to New PolarDB Endpoint), follow these steps:

        1. Select Switch without Endpoints (Application Needs to Be Reconfigured to New PolarDB Endpoint).

        2. Click OK.

        3. Refresh the page. When the Read/Write Status of the target PolarDB cluster changes to read and write, update the database endpoint in your applications as soon as possible.

      Note

      After the switchover, if you find data inconsistencies or other issues, you can perform a migration rollback to quickly restore the state before the upgrade. You can then choose to cancel the migration to revert to the state before the switchover.

    (Optional) Step 4: Switch over the source DTS task

    Note

    • If the source RDS instance has no associated DTS tasks (other than the one-click migration task), the button for this feature is not displayed. You can ignore this step.

    • If the source instance has an associated DTS task (other than the one-click migration task), you can use this feature to modify the source or destination instance of the DTS synchronization or migration task for a smooth business cutover. For information about the working principle and precautions, see Modify the source or destination instance of a DTS task.

    • During the schema synchronization and full data synchronization phases, do not perform DDL operations that change the database or table schema. Otherwise, the data migration task fails.

    1. Go to the PolarDB console.

    2. Find the target cluster and click its ID.

    3. In the RDS Migration section of the Basic Information page, click Source Instance DTS Task Switchover.

    4. In the Switch Over Business DTS Task Endpoint 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 data synchronization for the source and target instances. For more information, see View the status of a DTS task.

      • If you select Source Instance DTS Task (Forward Switchover), follow these steps:

        1. Select the DTS task whose database instance you want to switch over.

        2. Click Commit Forward Switchover.

      • If you select Target Instance DTS Task (Switchover Rollback), follow these steps:

        1. Select the DTS task whose database instance you want to roll back.

        2. Click Commit Switchover Rollback.

    Note

    • Source Instance DTS Task (Forward Switchover) applies after a switchover (Step 3) to switch an associated DTS task (other than the one-click migration task) from the source instance to the target instance. This operation is performed after the switchover (Step 3) and before you complete the migration (Step 5).

    • Target Instance DTS Task (Switchover Rollback) applies after a migration rollback to switch an associated DTS task (other than the one-click migration task) from the target instance back to the source instance. This operation is performed after an (Optional) migration rollback and before you (Optional) cancel the migration.

    Step 5: Complete the migration

    After you complete Step 1: Migrate from RDS, you must perform the Complete Migration operation within 30 days.

    Warning

    • Before you perform the Complete Migration operation, ensure that the data migration is complete and you no longer need data synchronization. For physical migration, this operation interrupts data replication from the source RDS instance to the PolarDB cluster. For logical migration, it deletes the data synchronization task.

    • This operation interrupts data synchronization between the PolarDB cluster and the RDS instance, and the (Optional) cancel migration feature becomes unavailable. We recommend that you run your business on the PolarDB cluster for a period of time to confirm that it runs as expected before you perform this operation.

    1. Log on to the PolarDB console.

    2. Find the target cluster and click its ID.

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

      Note

      • After you click OK, the system interrupts the synchronization relationship in about 2 minutes. During this time, the migration status is Disable Synchronization. Wait for the process to complete.

      • In the Complete Migration dialog box, you can choose whether to disable the binary log for the PolarDB cluster. Disabling the binary log provides a slight improvement in write performance, but the PolarDB cluster automatically restarts for the new configuration to take effect.

      • If the source RDS instance is no longer needed, you can manually unsubscribe from or release it. For details, see (Optional) Unsubscribe from or release the RDS instance.

      • If you need to renew or change the configuration of the source RDS instance, click Complete Migration first.

    (Optional) Release the RDS instance

    After data is migrated from RDS to PolarDB, if your business is running stably on PolarDB and you no longer need the source RDS instance, you can unsubscribe from or release it.

    (Optional) View DTS task details (for logical migration only)

    If you encounter a migration error (such as a precheck failure) or other exceptions (such as high replication latency) while upgrading by using logical migration (data synchronization by using DTS), you can view the details page of the corresponding DTS data synchronization task for more information.

    1. Go to the PolarDB console.

    2. Find the target cluster and click its ID.

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

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

      The task details page displays basic information (such as Task Instance ID, Task Name, Task Steps: schema synchronization → full data synchronization → incremental synchronization, Creation Time, Billing Method, Link Specification, and Region), source information (Instance Type: RDS Instance, Database Type: MySQL, Region, Instance ID, Connection Method: Non-encrypted Connection), and target information (Instance Type: Cloud Instance, Database Type: PolarDB MySQL, Region, Instance ID, Connection Method: Non-encrypted Connection). From the left-side navigation pane, you can switch to pages such as Synchronization Details, Performance Monitoring, Task Logs, and Synchronization Object Modification History.

    5. During the migration process, if you need to adjust the synchronization objects of the task (for example, if a new database is added to the source RDS instance and you want to include it in the synchronization), you can click Modify Synchronization Objects to reconfigure.