All Products
Search

This Product

    PolarDB:Upgrade steps

    Document Center

    PolarDB:Upgrade steps

    Last Updated:Mar 28, 2026

    This topic walks you through migrating an ApsaraDB RDS for MySQL instance to a PolarDB for MySQL cluster. PolarDB automatically creates the cluster, syncs your data, and inherits the accounts, databases, IP address whitelist, and required parameters from the source RDS instance.

    In this guide, you will:

    • Run prechecks to prepare the source RDS instance

    • Create a destination PolarDB cluster using the Migrate from RDS method

    • (Optional) Add endpoints to avoid connection changes after the switchover

    • Switch over services so the PolarDB cluster becomes the primary read/write database

    • (Optional) Switch over any existing DTS tasks

    • Complete the migration to finalize the process

    • (Optional) Release or unsubscribe from the source RDS instance

    Choose a migration method

    Two migration methods are available. Choose the one that matches your source instance:

    Physical migrationLogical migration
    How it worksDirectly replicates data at the storage levelSyncs data using Data Transmission Service (DTS)
    Supported source versionsRDS MySQL 5.6 or 5.7, High-availability Edition with local SSDsAll other RDS MySQL specifications
    Target versionSame MySQL version as the sourceSame or different MySQL version
    SpeedFaster, especially for large databasesSlower for large datasets; DTS reads and writes source and destination databases during full sync

    For a detailed comparison, see Comparison between physical migration and logical migration.

    Prechecks

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

    Note Skip this check if you have already completed migration evaluation with no issues. For more information, see Migration evaluation.

    Before running a logical migration, verify that the service-linked role for PolarDB exists and that Data Transmission Service (DTS) is authorized to access Alibaba Cloud resources.

    • Check whether the PolarDB service-linked role exists

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

      2. Check whether a role named AliyunServiceRoleForPolarDB appears in the list.

        • If the role exists, skip this check.

        • If the role does not exist, continue to the next step.

        image

      3. In the upper-left corner, click Create Role. On the Create Role page, click Create Service Linked Role in the upper-right corner.

        image

      4. On the Create Service Linked Role page, select ApsaraDB for PolarDB from the Select Service drop-down list, then click Create Service Linked Role.

        image

    • Check whether DTS is authorized

      Only the authorization check and fast authorization steps are described here. For the full authorization guide, see Authorize DTS to access Alibaba Cloud resources.

      Check authorization results

      1. Log on to the Roles page in the RAM console.

      2. Check whether a role named AliyunDTSDefaultRole appears in the list.

        • If the role does not exist, perform fast authorization (see below).

        • If the role exists, continue to the next step to verify its permissions.

        image

      3. Click AliyunDTSDefaultRole to view its details. The role is properly authorized if all of the following are true: If either condition is not met, delete AliyunDTSDefaultRole and authorize again.

        • The AliyunDTSRolePolicy policy appears on the Permissions tab. image

        • dts.aliyuncs.com appears on the Trust Policy tab. image

      Fast authorization

      Log on to the Roles page in the RAM console. In the Authorize Access to Cloud Resources dialog box, click Authorize.

      Note

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

    Note Skip this check if you have already completed migration evaluation with no exceptions. For more information, see Migration evaluation.

    To prevent system accounts in the destination PolarDB cluster from being overwritten during migration, make sure the source RDS instance does not contain both root and aliyun_root at the same time. The correct system account depends on the RDS MySQL version:

    RDS MySQL versionCorrect system account
    RDS MySQL 5.6root
    RDS MySQL 5.7aliyun_root
    RDS MySQL 8.0aliyun_root

    Remove any account that is not listed as correct for your version. For example, if you are running RDS MySQL 5.7 and you created root manually in the console, remove it before starting the migration. First confirm the account is not used in production.

    Note Extra system accounts may have been created manually or inherited from a previous version upgrade. Some accounts may not be visible in the console.

    The following example shows how to remove extra system accounts from an RDS MySQL 5.6 instance:

    1. Connect to the database using a privileged account.

    2. Find all root and aliyun_root system accounts:

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

    3. Remove the extra account. For RDS MySQL 5.6, root is correct, so remove aliyun_root:

      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 the read-only RDS instance are different, merge the read-only instance's whitelist into the primary instance's whitelist before starting the migration. This ensures the read-only instance's whitelist is automatically synchronized to the destination PolarDB cluster.

    Step 1: Create a destination PolarDB cluster

    Create a PolarDB cluster that mirrors the data in the source RDS instance. After the cluster is created, incremental data is continuously synchronized from the source RDS instance to the PolarDB cluster in real time.

    Note

    • Complete migration evaluation before starting. For more information, see Migration evaluation.

    • Make sure the storage space available in the PolarDB cluster exceeds the storage used by the source RDS instance.

    • For logical migration, DTS reads and writes both the source and destination databases during full data synchronization, which may increase database load. To limit the impact, enable throttling. For more information, see Enable throttling for data migration.

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

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

      • Subscription: Pay upfront for compute nodes. Storage is billed based on actual hourly usage.

      • Pay-as-you-go: No upfront payment. Compute node and storage fees are deducted hourly based on actual usage.

      • Serverless: No upfront payment. Compute nodes, storage, and PolarProxy scale dynamically based on demand. Fees are based on actual usage.

    3. Configure the cluster parameters. Key parameters are described in the following table.

      Note For parameters not listed here, see Purchase a cluster.
      ParameterDescription
      Creation methodSelect Migrate from RDS. The PolarDB cluster operates in read-only mode until the migration is complete. Binary logging is enabled by default.
      RegionThe region where the source RDS instance is deployed. The destination PolarDB cluster must be in the same region.
      RDS engine typeThe database engine of the source RDS instance. Fixed to MySQL.
      RDS engine versionThe MySQL version of the source RDS instance: 5.6, 5.7, or 8.0.
      Source RDS instanceThe source RDS instance to migrate from. Read-only instances are excluded.
      Database engineThe MySQL version for the destination PolarDB cluster. Can be the same as or different from the source version.
      Node specificationsThe compute node specifications. Select specifications equal to or higher than those of the source RDS instance. For available specifications, see Compute node specifications of PolarDB for MySQL Enterprise Edition.
      Storage engineInnoDB or InnoDB & X-Engine. If you select InnoDB & X-Engine, you can specify the X-Engine memory usage ratio. For more information, see X-Engine.

    4. In the upper-right corner, review the configuration, then set the Duration, Quantity, and Auto-renewal parameters. Duration applies only to subscription clusters.

    5. Read and accept the terms of service, then click Confirm Order.

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

      Note

      • After payment, wait 10 to 15 minutes for the cluster to appear on the Clusters page.

      • If nodes show Creating status, the cluster is still initializing. The cluster is available only when its status is Running.

      • Make sure you select the correct region. Otherwise, the cluster will not appear in the list.

    7. After the cluster is created, click the cluster ID to open the Basic Information page.

    8. In the RDS Migration section, monitor the Replication Latency value. When it drops below 60 seconds, you can proceed to 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, data synchronization from the RDS instance begins. Complete Step 5 within 30 days of creating the cluster. If you do not, the migration task is automatically disabled.

      • For logical migration: if the RDS Migration section shows Precheck Failed after the cluster is created, follow the instructions in the error message to troubleshoot.预检查失败

        For example, if the source RDS instance contains a trigger, the precheck fails with "The RDS instance has a trigger." Delete the trigger and click Continue Migration, or click Cancel Migration and 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 also click Cancel Migration at this stage. For information about the impacts of cancelling migration, see FAQ.

      基本信息

    (Optional) Step 2: Add endpoints

    If you want to switch over services without changing application connection strings, select the Switch with Endpoints (Connection Changes Not Required) option during the switchover. This interchanges the endpoints between the source RDS instance and the destination PolarDB cluster automatically. After the switchover, your applications connect to PolarDB using the original connection string.

    For endpoint interchange to work, both the source RDS instance and the destination PolarDB cluster must have matching endpoints. By default, PolarDB creates only a private primary endpoint and a private cluster endpoint. If the source RDS instance has additional endpoints, create the corresponding endpoints in PolarDB before the switchover.

    Note

    • If you do not add endpoints before the switchover, add them after the switchover once the PolarDB cluster is in the running state.

    • To interchange private endpoints, the source RDS instance and the destination PolarDB cluster must belong to the same virtual private cloud (VPC). If they are in different VPCs, existing services will lose connectivity after the switchover.

    Step 3: Switch over services

    When the Replication Latency in the RDS Migration section drops below 60 seconds, perform the switchover.

    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.

      Note

      • The switchover typically takes about 5 minutes.

      • After the switchover, the source RDS instance changes to Read-only and the PolarDB cluster changes to Read and Write. Incremental data then replicates from the PolarDB cluster back to the RDS instance.

      image

    4. In the Switches the business over to the new database dialog box, select a switchover method.

      • Switch with Endpoints (Connection Changes Not Required) The system interchanges the endpoints between the RDS instance and the PolarDB cluster. Applications connect to PolarDB using the existing connection string, with no configuration changes required. > Important: Before selecting this option, review the notes for switchover with endpoints. Click OK, then confirm in the dialog box.

      • Switch without Endpoints (Connection Changes Required) Click OK, then confirm in the dialog box. After the switchover completes, refresh the page. When the PolarDB Read/Write Status changes to Read and Write, update the database endpoint in your applications.

      image

    Note If data errors occur after the switchover, roll back to restore the database to its pre-switchover state. For more information, see Roll back the migration. To fully restore the status before the migration started, see Cancel migration.

    (Optional) Step 4: Switch over DTS tasks

    Note

    • If the source instance is not involved in a DTS task (other than a one-click migration task), theBusiness DTS Task Database Endpoint Switchoverbutton does not appear in the console. Skip this step.

    • During schema migration and full data migration, do not run DDL statements that change database or table schemas. Doing so causes the migration task to fail.

    If the source instance is involved in a DTS task (not a one-click migration task), modify the source or destination database of the DTS task for a smooth switchover. For details on how this feature works, see ModifyDtsJobEndpoint.

    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 Business DTS Task Database Endpoint Switchover.

      image

    4. In the Business DTS Task Database Endpoint Switchover dialog box, select an option.

      • Source Instance DTS Task (Forward Switchover): Select the DTS task of the source RDS instance, then click Commit Forward Switchover.

      • Destination Instance DTS Task (Switchover Rollback): image Select the DTS task of the destination PolarDB cluster, then click Commit Switchover Rollback.

      Important

      Before proceeding, check the status of the DTS synchronization tasks for both the source RDS instance and the destination PolarDB cluster. For details, see DescribeDtsJobDetail.

      image

    Note

    • Forward Switchover: Use this option after Step 3 (Switch over services) but before Step 5 (Complete the migration). This switches the DTS task from the source RDS instance to the PolarDB cluster.

    • Switchover Rollback: Use this option after rolling back the migration but before canceling it. This returns the DTS task from the PolarDB cluster to the source RDS instance.

    Step 5: Complete the migration

    After creating the PolarDB cluster in Step 1, click Complete Migration within 30 days.

    Warning

    • Only click Complete Migration after confirming that data migration is complete and you no longer need data synchronization. For physical migration, this terminates data replication from the RDS instance to the PolarDB cluster. For logical migration, this deletes the DTS data synchronization task.

    • This operation permanently breaks data synchronization between the PolarDB cluster and the RDS instance. The Cancel Migration option will no longer be available. Run the PolarDB cluster in production for a period of time and verify it is stable before completing 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, click OK.

      Note

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

      • In the Complete Migration dialog box, you can choose to disable binary logging for the PolarDB cluster. Disabling binary logging slightly improves write performance. The cluster automatically restarts for the change to take effect.

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

      image

    (Optional) Release or unsubscribe from the source RDS instance

    After confirming that your services run correctly on the PolarDB cluster and you no longer need the source RDS instance, release or unsubscribe from it:

    (Optional) View DTS data synchronization task details (logical migration only)

    If you encounter migration errors (such as a precheck failure) or anomalies (such as high replication latency) during a logical migration, view the DTS task details to diagnose the issue.

    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 the DTS Data Synchronization Task name to open the task list in the DTS console.

      DTS任务

    4. Find the synchronization task. You can view precheck failure details, task details, and task logs. 任务详情

    5. To add new databases to the synchronization scope during migration, click Reselect Objects.

      image