All Products
Search

This Product

    PolarDB:Upgrade steps

    Document Center

    PolarDB:Upgrade steps

    Last Updated:Sep 22, 2026

    During the one-click upgrade from RDS for MySQL to PolarDB for MySQL, a target PolarDB cluster is created and data synchronization begins. The upgraded PolarDB cluster retains account information, databases, IP whitelists, and necessary parameter settings from the source RDS instance.

    The overall upgrade process includes the following steps:

    Note

    • One-click upgrade supports two migration methods: physical migration (physical replication) and logical migration (DTS data synchronization). The differences are described below. For more information, see Comparison between physical migration and logical migration.

      • Physical migration (physical replication): RDS for MySQL 5.6 and 5.7 High-availability Edition instances with local SSD storage are migrated to PolarDB for MySQL clusters of the same version.

      • Logical migration (DTS data synchronization): All other RDS for MySQL instance types not covered by physical migration (physical replication) are migrated to PolarDB for MySQL clusters of the same or a different version.

    • For detailed step descriptions, see each operation step.

    1. Pre-checks:

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

    3. Step 2: Address replenishment (optional): One-click upgrade supports switching with address transfer. You can retain the source RDS instance endpoint so that applications can switch to the target PolarDB cluster without modifying any connection configurations. Only endpoints that exist on both the source RDS instance and the target PolarDB cluster simultaneously support mutual switching.

    4. Step 3: Migration cutover: Swap the read/write states of the source RDS instance and the target PolarDB cluster (that is, change the source RDS instance to Read Only and the target PolarDB cluster to Read/Write), while reversing the replication direction (synchronizing new data from the target PolarDB cluster back to the source RDS instance).

    5. Step 4: Source instance DTS task cutover (optional): If the source instance has associated DTS links (not the one-click migration DTS link), you can use this feature to modify (replace) the source or target instance in a DTS synchronization or migration task to smoothly switch associated workloads.

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

    7. Unsubscribe from or release the RDS instance (optional): 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 the source RDS instance.

    After the migration cutover is complete, if you find data anomalies or other issues, you can perform a Roll back migration (Optional) operation to quickly restore to the pre-upgrade state. You can then choose to perform a Cancel migration (Optional) operation to restore to the state before the cutover.

    Pre-checks

    Check whether a PolarDB service-linked role has been created (logical migration only)

    Note

    If you have completed Migration evaluation without any exceptions, you can skip this pre-check.

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

    • Check whether a PolarDB service-linked role has been created

      1. Log on to the RAM console using your Alibaba Cloud account and go to Identity Management > Role list.

      2. In the role list, check whether a service-linked role named AliyunServiceRoleForPolarDB exists, as follows: enter the role name AliyunServiceRoleForPolarDB in the search box and confirm the service-linked role appears in the list.

        • If it exists, skip this check.

        • If it does not exist, proceed with the following steps.

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

      4. On the Create Service-linked Role page that opens, set Trusted Cloud Service to AliyunServiceRoleForPolarDB and click Create Service-linked Role to complete the creation.

    • Check whether DTS has been authorized to access cloud resources

      The following shows how to view the authorization result and how to quickly grant authorization. For more information, see Grant DTS permissions to access cloud resources.

      View authorization result

      1. Log on to the RAM console using your Alibaba Cloud account and go to Identity Management > Role list.

      2. In the role list, check whether a role named AliyunDTSDefaultRole exists, as follows: enter AliyunDTSDefaultRole in the search box and confirm whether the role appears in the list.

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

        2. If it exists, continue with the following steps to check the current role permissions.

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

        • The authorization is successful when AliyunDTSDefaultRole meets all of the following conditions simultaneously.

          • Permission Management includes system policy AliyunDTSRolePolicy.

          • Trust Policy includes dts.aliyuncs.com.

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

        • When AliyunDTSDefaultRole does not meet the above conditions, authorization has failed and re-authorization is required. You can delete the role AliyunDTSDefaultRole and re-authorize.

      Quick authorization

      Log on to the AliyunDTSDefaultRole quick authorization page using your Alibaba Cloud account. On the RAM quick authorization page, click Submit.

      Note

    Delete redundant system accounts from the source RDS instance (logical migration only)

    Note

    If you have completed Migration evaluation without any exceptions, you can skip this pre-check.

    To ensure compatibility between the RDS for MySQL and PolarDB system account systems and to prevent the system accounts of the target PolarDB from being overwritten after the upgrade, the source RDS instance cannot have both root and aliyun_root accounts at the same time. Therefore, before the upgrade, delete any redundant system accounts from the source RDS instance.

    The correct system account names for each RDS for MySQL version are as follows:

    RDS for MySQL version

    Correct system account name

    RDS MySQL 5.6

    root

    RDS MySQL 5.7

    aliyun_root

    RDS MySQL 8.0

    aliyun_root

    For each version listed above, all system accounts other than the correct one must be deleted. For example, the correct system account for an RDS MySQL 5.7 instance is aliyun_root. If you manually created a root account in the console, you must delete it. Before deleting, make sure your workloads are not using the root account.

    Note

    System accounts may have been created manually or created by the system and left over due to a version upgrade. In some cases, the account may not be displayed in the console.

    Example

    The following uses an RDS MySQL 5.6 instance as an example to show how to delete redundant system accounts:

    1. Connect to the instance 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 redundant system account. For RDS MySQL 5.6, the correct system account is root, so you need to delete the aliyun_root account.

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

    Whitelist check (optional)

    If the whitelist configurations of the source RDS primary instance and read-only instances are inconsistent, merge the read-only node whitelist into the primary node whitelist before the migration to ensure that the read-only node whitelist is automatically synchronized to the target PolarDB cluster.

    Zone selection (optional)

    If the zone where the source RDS instance resides does not currently support PolarDB, you can select a different zone to create a 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 the PolarDB cluster in real time.

    Note

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

    • Before starting the migration, make sure the PolarDB cluster storage capacity is greater than that of the source RDS instance.

    • When using DTS for migration, initial full data synchronization occupies read and write resources on both the source and target databases, which may increase the database load. You can adjust the synchronization rate as needed. For detailed steps, see Enable throttling for data migration.

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

    2. Select Billing Method as Subscription, Pay-As-You-Go, or Serverless.

      • Subscription: You pay for compute node fees when creating the cluster. Storage space is billed by the hour based on actual data volume and deducted from your account hourly.

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

      • Serverless: No prepayment is required. Compute nodes, storage space, database proxy, and other resources dynamically scale based on actual demand during cluster use and are billed based on actual usage.

    3. Configure the following parameters.

      Note

      For parameters not described in detail in the table below, see the relevant section in Purchase a cluster.

      Parameter

      Description

      Creation Method

      Select Migrate from RDS.

      Note

      Before the migration cutover, the PolarDB read/write state is read-only, and Binlog is enabled by default.

      Region

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

      Note

      The new PolarDB cluster will also be in this region.

      Source RDS Engine

      The engine type of the source RDS instance, fixed at 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 instance. Read-only instances are not included.

      Compatibility

      The database engine version of the target PolarDB cluster. You can select the same version as the source RDS instance or a cross-version.

      Node Specifications

      Select as needed. We recommend a specification no lower than the source RDS instance. For 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, review the cluster configuration, set the Subscription Duration (for Subscription clusters), Quantity, and whether to enable Auto-renewal.

    5. Read and accept the Terms of Service. Click Buy Now.

    6. On the Payment page, verify the unpaid order information and payment method, then click Order.

      Note

      • After successful payment, wait 10 to 15 minutes for the cluster to be created. You can then view the newly created cluster in the Cluster List.

      • When the status of nodes in the cluster shows Creating, the entire cluster may not have finished creation and is not yet available. The cluster is ready to use only when the cluster status shows Running.

      • Make sure the correct region is selected; otherwise, you will not be able to find your newly created cluster.

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

    8. On the Basic Information page, in the RDS Migration section, confirm that the Replication Latency of the target PolarDB cluster is less than 60 seconds before proceeding to the Step 3: Migration cutover operation.

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

      Note

      • Instances with existing DTS two-way synchronization cannot perform one-click migration/upgrade and may encounter data inconsistency issues;

      • After the cluster is created, it begins synchronizing data from the RDS instance. You must complete the Step 5: Complete migration operation within 30 days; if 30 days elapse, the migration feature will be automatically disabled.

      • For logical migration (DTS data synchronization), after the PolarDB cluster is created, if the RDS migration status changes to Pre-check failed, follow the prompts in Error Message to resolve the issue.

        For example, if triggers exist in the source RDS, the pre-check will fail with the error "RDS instance has triggers". Delete the triggers from the source RDS first, then click Continue migrating, or click Give up migration and manually create a migration task in the DTS console. For more information, see Configure tasks for source databases with triggers.

      • You can choose Give up migration at this step. For the related impact, see FAQ.

    Step 2: Address replenishment (optional)

    PolarDB one-click migration supports switching with address transfer. You can retain the original database endpoint so that applications can switch to PolarDB without modifying any connection configurations. Note that only endpoints that exist on both the source RDS and the target PolarDB cluster simultaneously support mutual switching. By default, the target side only creates a private primary endpoint and a private cluster endpoint. If the source side has more than two endpoints, you must create the corresponding endpoints on the target side before switching; otherwise, they will not be switched. For information about creating endpoints for PolarDB clusters and RDS instances, see Manage endpoints and Configure endpoints for an RDS instance.

    Note

    • Address replenishment can only be performed after the target cluster is in the Running state. You can also configure address attributes, instance parameters, and replenish read-only nodes based on your business needs.

    • Before switching private endpoints using the address transfer method, make sure the source RDS instance and the target PolarDB cluster are in the same VPC; otherwise, the original service will be unable to connect after the switch.

    Step 3: Migration cutover

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

    1. Go to the PolarDB console.

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

    3. On the Basic Information page, in the RDS Migration section, click Switch Over.

      The DTS data synchronization task displayed on the page is a free task. Do not manually operate this task; doing so will cause the migration to fail.

      Note

      • The cutover process generally takes less than 5 minutes.

      • This operation swaps the read/write states of the source RDS instance and the target PolarDB cluster (that is, changes the source RDS instance to Read-only and the PolarDB cluster to Read/Write), while reversing the replication direction (synchronizing new data from the PolarDB cluster to the RDS instance).

    4. In the Switch Business to New Database dialog box, select Switch with address transfer (no connection configuration changes required for applications) or Switch without address transfer (applications need to update to the new PolarDB connection configuration).

      • If you select Switch with address transfer (no connection configuration changes required for applications), proceed as follows:

        1. Select Switch with address transfer (no connection configuration changes required for applications). The system automatically swaps the endpoints on the source RDS instance and the target PolarDB, and your applications will automatically connect to the target PolarDB cluster without any configuration changes.

          Important

          Before selecting Switch with address transfer (no connection configuration changes required for applications), make sure you read Notes for switching with address transfer.

        2. Click OK.

      • If you select Switch without address transfer (applications need to update to the new PolarDB connection configuration), proceed as follows:

        1. Select Switch without address transfer (applications need to update to the new PolarDB connection configuration).

        2. Click OK.

        3. Refresh the page. After the target PolarDB Read/Write Status shows Read/Write, update the database endpoint in your application as soon as possible.

      Note

      After the migration cutover is complete, if you find data anomalies or other issues, you can perform a Migration Rollback operation to quickly restore to the pre-upgrade state. You can then choose to perform a Cancel Migration operation to restore to the state before the cutover.

    Step 4: Source instance DTS task cutover (optional)

    Note

    • If the source RDS instance has no associated DTS task links (not the one-click migration DTS link), the feature button for this step will not appear on the current page. Skip this step.

    • If the source instance has associated DTS links (not the one-click migration DTS link), you can use this feature to modify (replace) the source or target instance in a DTS synchronization or migration task to smoothly switch associated workloads. For the implementation principles and notes, see ModifyDtsJobEndpoint.

    • During the schema migration and full data migration phases, do not perform DDL operations that change the database or table schema; otherwise, the data migration task will fail.

    1. Go to the PolarDB console.

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

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

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

      Important

      Before switching, check the DTS status for data synchronization between the source and target instances. For detailed DTS status query, see DTS status query.

      • If you select Source Instance DTS Task (Forward Cutover), proceed as follows:

        1. Select the DTS task for which you want to switch the database instance.

        2. Click Commit Forward Switchover.

      • If you select Target Instance DTS Task (Rollback Cutover), proceed as follows:

        1. Select the DTS task for which you want to switch the database instance.

        2. Click Commit Switchover Rollback.

    Note

    • Source Instance DTS Task (Forward Cutover) is used after Migration Cutover (Step 3) to switch the DTS link (not the one-click migration DTS link) associated with the source instance to the target instance. This operation is performed after Migration Cutover (Step 3) and before Complete Migration (Step 5).

    • Target Instance DTS Task (Rollback Cutover) is used after Migration Rollback to switch the DTS link (not the one-click migration DTS link) associated with the target instance back to the source instance. This operation is performed after Migration Rollback (Optional) and before Cancel migration (Optional).

    Step 5: Complete migration

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

    Warning

    • Before performing the Complete Migration operation, make sure that data migration is complete and data synchronization is no longer required. For physical migration, this will interrupt data replication from the source RDS to the PolarDB cluster. For logical migration, the data synchronization task will be deleted.

    • Since this operation interrupts data synchronization between the PolarDB cluster and the RDS instance, the Cancel migration (Optional) feature will no longer be available. We recommend that you use the PolarDB cluster for a period of time and confirm that everything is working properly before performing this operation.

    1. Log on to the PolarDB console.

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

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

      Note

      • After clicking OK, the system will interrupt the synchronization relationship in approximately 2 minutes. During this time, the migration status will show Disable Synchronization. Wait patiently for the migration to complete.

      • In the Complete Migration dialog box, you can choose whether to disable Binlog for the PolarDB cluster. Disabling Binlog provides a slight write performance improvement, but will cause the PolarDB cluster to automatically restart to apply the new configuration.

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

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

    Unsubscribe from or release the RDS instance (optional)

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

    View data synchronization task details (logical migration only) (optional)

    When using logical migration (DTS data synchronization) for one-click upgrade, if you encounter migration errors (such as pre-check failures) or other abnormal states (such as unusually high replication delay), you can go to the corresponding DTS data synchronization task details page to view specific information about the task.

    1. Go to the PolarDB console.

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

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

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

      The synchronization task details page shows basic information (task instance ID, task name, task steps: Schema Synchronization → Full Synchronization → Incremental Synchronization, creation time, billing method, link specifications, region, etc.), 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). The left navigation panel can be switched to Synchronization Details, Performance Monitoring, Task Logs, Synchronization Object Change Records, and other pages.

    5. During migration, if you need to modify the synchronization objects of the sync task (for example, if a new database is added to the source RDS and needs to be included in the sync objects), click Modify Synchronization Objects to reconfigure.