All Products
Search

This Product

    PolarDB:One-click upgrade from RDS for MySQL to PolarDB for MySQL

    Document Center

    PolarDB:One-click upgrade from RDS for MySQL to PolarDB for MySQL

    Last Updated:Jun 02, 2026

    PolarDB lets you upgrade an ApsaraDB RDS for MySQL instance to a PolarDB for MySQL cluster with one click. PolarDB automatically syncs accounts, databases, IP whitelists, and parameters from the source RDS instance. You can retain the original endpoint so applications switch to the PolarDB cluster without configuration changes.

    You can upgrade an RDS instance to a PolarDB cluster of the same or a higher version. For example:

    • An ApsaraDB RDS for MySQL 5.6 instance can be upgraded to a PolarDB for MySQL 5.6, 5.7, 8.0.1, or 8.0.2 cluster.

    • An ApsaraDB RDS for MySQL 5.7 instance can be upgraded to a PolarDB for MySQL 5.7, 8.0.1, or 8.0.2 cluster.

    • An ApsaraDB RDS for MySQL 8.0 instance can be upgraded to a PolarDB for MySQL 8.0.1 or 8.0.2 cluster.

      Note

      • PolarDB for MySQL 8.0.1 is fully compatible with MySQL Community Edition 8.0.13 and earlier. Version 8.0.2 is fully compatible with MySQL Community Edition 8.0.18 and earlier.

      • The features supported by PolarDB for MySQL 8.0.1 and 8.0.2 differ. Feature comparison of kernel versions.

    Migration methods

    Two migration methods are available: physical migration (physical replication) and logical migration (DTS data synchronization). The system selects the method based on the MySQL version, edition, and storage type of the RDS instance. You cannot change the method.

    Item

    Physical migration (physical replication)

    Logical migration (DTS data synchronization)

    Applicable instance

    ApsaraDB RDS for MySQL 5.6 and 5.7 High-availability Edition instances that use local SSDs. These instances can be upgraded to PolarDB for MySQL clusters of the same version.

    Note

    Minor version requirements:

    • For ApsaraDB RDS for MySQL 5.6 High-availability Edition, the minor version must be 20190815 or later.

    • For ApsaraDB RDS for MySQL 5.7 High-availability Edition, the minor version must be 20200331 or later.

    Except for the physical migration (physical replication) method, other types of RDS for MySQL instances can be upgraded to PolarDB for MySQL clusters of the same or a different version.

    Note

    No minor version restrictions.

    How it works

    Copies the full data from the RDS instance and then maintains incremental synchronization to the PolarDB cluster.

    Important

    During incremental synchronization, any non-InnoDB tables that are created are converted to InnoDB tables.

    Uses DTS to create a task that performs full data and schema synchronization from the RDS instance to the PolarDB cluster, followed by incremental synchronization.

    Note

    • During full data initialization, concurrent INSERT operations cause table fragmentation in the PolarDB cluster. Therefore, after the full initialization is complete, the tablespace of the PolarDB cluster is larger than that of the RDS instance.

    • High memory usage can occur during the full data initialization phase. This is because the InnoDB engine's memory buffer pool, innodb_buffer_pool, actively caches data to accelerate read and write operations, which increases overall memory usage. After a one-click upgrade is complete, you can adjust the size of the memory buffer, innodb_buffer_pool_size, in the console to reduce this portion of memory usage.

    DTS required

    No.

    Yes.

    Migrate MySQL version

    Only same-version migration is supported.

    Supports migration to the same or a higher version.

    Upgrade duration limit

    You must complete the migration within 30 days. After this period, the migration feature is disabled.

    You must complete the migration within 30 days. After this period, the migration feature is disabled.

    Cross-region migration

    Not supported.

    Not supported.

    Incremental synchronization

    Supported.

    Supported.

    Migration of new databases

    Supported.

    Not supported.

    Note

    To synchronize new databases, go to the DTS console to modify the synchronization objects. Add the new databases to both the forward and reverse synchronization tasks.

    Schema migration

    Supported.

    Only the schemas of databases, tables, views, stored procedures, and functions can be migrated.

    Benefits

    • Switchover with endpoints: You can retain the original database endpoint, allowing your applications to switch to the PolarDB cluster without modifying any connection configurations.

    • The one-click upgrade process ensures zero data loss.

    • Supports incremental migration.

    • Supports online hot migration. Your service experiences only a single brief interruption of less than 10 minutes during the switchover operation.

    • Supports migration rollback. You can roll back the migration within 10 minutes if it fails or if your business requirements change.

    Impact on RDS instances

    The one-click upgrade restricts some operations on the RDS instance and may cause a brief interruption or increased load.

    • You cannot modify instance parameters during the one-click upgrade process.

    • During the one-click upgrade process, you cannot unsubscribe from, release, or change the zone of the RDS instance.

    • During the switchover operation, if you choose Switchover with Endpoints, your business may be interrupted for 1 to 5 minutes. If you choose Switchover without Endpoints, you must promptly update your application's connection settings to connect to the PolarDB cluster.

    • According to the migration method, if you perform a one-click upgrade by using logical migration (DTS data synchronization), the following impacts apply:

      • If triggers exist on the RDS instance, you must delete them before starting. Otherwise, the migration will be interrupted.

      • During full data initialization, do not perform DDL operations that alter database or table schemas. This can cause the data synchronization task to fail.

      • Full data initialization consumes read and write resources, such as CPU and IOPS, on both the RDS instance and the PolarDB cluster. This may increase the load on the RDS instance.

    Usage notes

    Prerequisites

    Your RDS instance must meet the following conditions:

    • Instance specifications:

      MySQL version

      Basic Edition

      High-availability Edition

      Cluster Edition

      5.6

      -

      local SSD

      -

      5.7

      cloud disk

      local SSD, cloud disk

      cloud disk

      8.0

      cloud disk

      local SSD, cloud disk

      cloud disk

    • The storage engine type for the data table must be InnoDB or X-Engine.

    • If your instance does not meet the requirements for physical migration (physical replication), the system will automatically select logical migration (DTS data synchronization) for the upgrade. In this case, to prevent the one-click upgrade from failing, the RDS instance must also meet the following conditions:

      • The RDS instance must not be part of any existing DTS bidirectional synchronization tasks. Proceeding with the upgrade in this case can cause data inconsistency.

      • If triggers exist on the RDS instance, you must delete them before starting. Otherwise, the migration will be interrupted.

      • Binary logging is enabled by default on the RDS instance. Ensure that the binlog_row_image parameter is set to full. Otherwise, an error is reported during the precheck, and the data synchronization task cannot start.

      • DTS requires that the binary logs of the RDS instance be retained for at least seven days. Otherwise, DTS may fail to obtain the binary logs, causing the task to fail and, in extreme cases, leading to data inconsistency or loss. Issues caused by setting a binary log retention period shorter than the DTS requirement are not covered by the DTS Service Level Agreement (SLA).

    • If your instance does not meet the requirements for physical migration (physical replication), but you want to use this method to perform a one-click upgrade, you can perform the following operations to make your RDS instance meet the requirements for physical migration (physical replication), and then perform the one-click upgrade:

      • For ApsaraDB RDS for MySQL 5.6 High-availability Edition, the minor version must be 20190815 or later.

      • For ApsaraDB RDS for MySQL 5.7 High-availability Edition, the minor version must be 20200331 or later.

      Note

      • You can go to the RDS console > Instance Details > Basic Information page. In the Configurations section, view the minor version information of the RDS instance. If the version is lower than the one specified above, you can upgrade the minor version to the latest version.

      • For physical migration (physical replication), set the retention period for binary logs to at least 24 hours.

    Limitations

    If your instance does not meet the requirements for physical migration (physical replication), the system automatically selects logical migration (DTS data synchronization) to perform the upgrade. This migration method has the following usage limitations:

    • Do not write data to the destination database except through DTS while synchronization is running. Otherwise, data inconsistency may occur between the source and destination databases. For example, if you use DMS to perform online DDL operations while other data is written to the destination database, data loss may occur.

    • DTS disables foreign key constraints by default when synchronizing to a destination database. Therefore, cascading operations and deletions in the source database are not synchronized to the destination database.

    • SQL statements supported for incremental synchronization:

      Operation type

      SQL statement

      DML

      INSERT, UPDATE, DELETE

      DDL

      • ALTER TABLE, ALTER VIEW

      • CREATE FUNCTION, CREATE INDEX, CREATE PROCEDURE, CREATE TABLE, CREATE VIEW

      • DROP INDEX, DROP TABLE

      • RENAME TABLE

      • TRUNCATE TABLE

    Considerations

    Migration phase

    Description

    Before migration

    During migration

    • When you create the PolarDB cluster, the full data synchronization is initiated. The duration depends on the data volume, and the cluster status is Creating during this process.

    • When you perform an (Optional) switchover with endpoints, only the connection endpoints that exist on both the RDS instance and the PolarDB cluster can be switched. You must create the corresponding connection endpoints on the cluster before the switchover. Otherwise, the switchover will not occur.

    • The SSL encryption status of the endpoints must match:

    • For logical migration (DTS data synchronization), do not manually release the DTS data synchronization task.

    Billing

    Logical migration (DTS data synchronization)

    For the logical migration (DTS data synchronization) method, you are charged for the DTS data synchronization task and the target PolarDB cluster.

    • DTS data synchronization task:

      During the upgrade, the system automatically creates a DTS data synchronization task between the RDS instance and the PolarDB cluster. DTS billing overview.

    • Target PolarDB cluster:

      • If the billing method is pay-as-you-go, the cluster is not billed during the upgrade process. Standard pay-as-you-go billing begins after one of the following operations:

        • Migration is completed (including the Complete Migration operation).

          Note

          • Migration is complete when the synchronization link between the RDS instance and the PolarDB cluster terminates.

          • The migration must be completed within 30 days. After this period, the migration feature is disabled, and both the RDS instance and the PolarDB cluster revert to read/write status, breaking the replication link.

        • Migration is stopped (including the Abandon Migration operation for precheck failures and the Cancel Migration operation).

          At this point, the target PolarDB cluster has been created, but the upgrade process is stopped. If you no longer need the target PolarDB cluster, release it promptly.

      • If the billing method is Serverless, billing starts once the cluster status changes to Running.

      • If the billing method is subscription, you must pay the corresponding fee when you create the cluster.

    Physical migration (physical replication)

    For the physical migration (physical replication) method, there are no extra fees for the upgrade process. You are only charged for the target PolarDB cluster.

    • If the billing method is pay-as-you-go, the cluster is not billed during the upgrade process. Standard pay-as-you-go billing begins after one of the following operations:

      • Migration is completed (including the Complete Migration operation).

        Note

        • Migration is complete when the synchronization link between the RDS instance and the PolarDB cluster terminates.

        • The migration must be completed within 30 days. After this period, the migration feature is disabled, and both the RDS instance and the PolarDB cluster revert to read/write status, breaking the replication link.

      • Migration is stopped (including the Abandon Migration operation for precheck failures and the Cancel Migration operation).

        At this point, the target PolarDB cluster has been created, but the upgrade process is stopped. If you no longer need the target PolarDB cluster, release it promptly.

    • If the billing method is Serverless, billing starts once the cluster status changes to Running.

    • If the billing method is subscription, you must pay the corresponding fee when you create the cluster.

    Get started

    1. Migration assessment

    PolarDB provides a migration assessment feature to pre-check instance status, task dependencies, and instance attributes before you start. This helps identify and resolve potential issues early.

    2. Upgrade steps

    Console operations

    This section outlines the one-click upgrade process. Upgrade steps.

    1. (Optional) Check the IP address whitelist

      If your RDS instance has read-only instances and their IP address whitelists are different from the primary instance's whitelist, merge the whitelists of the read-only instances into the primary instance's whitelist. This ensures that the whitelists are automatically synchronized to the PolarDB cluster.

      Note

      The IP address whitelist of a PolarDB cluster applies to the entire cluster. You cannot configure separate whitelists for individual nodes. Therefore, after the migration is complete, review the IP address whitelist and database account permissions for the PolarDB cluster.

    2. Create a PolarDB cluster

      Go to the PolarDB cluster purchase page. Set the creation method to Migrate from RDS, and specify the version and instance of the source RDS instance to purchase a PolarDB cluster. After the purchase is complete, the system performs initialization, a pre-check, and full data synchronization. During this process, the cluster status is Creating. Please wait.

      Note

      During logical migration (DTS data synchronization), an error such as Precheck Failed may occur. Resolve the error based on the Error Message. After you resolve the error, click Continue to resume the one-click upgrade process. If resolving the error affects your online services, you can click Abandon Migration to stop the upgrade process.

    3. (Optional) Add missing endpoints

      The switchover with endpoints feature retains the original database endpoints. This lets your applications switch to the PolarDB cluster without changing any connection settings. However, you can only switch over endpoints that exist on both the RDS instance and the PolarDB cluster.

      1. As needed, add the required database endpoints on the PolarDB cluster.

      2. Check the SSL encryption status of the database endpoints. The SSL status for the RDS instance and PolarDB cluster endpoints must be the same.

    4. Switchover

      When the Replication Latency of the PolarDB cluster is less than 60 seconds, you can switch over your services. Click Switch Over. This action swaps the read/write status of the RDS instance and the PolarDB cluster. The RDS instance becomes read-only, and the PolarDB cluster becomes read/write. The data replication direction is also reversed. New data from the PolarDB cluster is synchronized to the RDS instance.

      Important

    5. (Optional) Switch the DTS task of the source instance

      If the RDS instance has an associated Data Transmission Service (DTS) link, other than the one used for logical migration in this upgrade process, you can use this feature. This feature lets you change the source or destination instance of the DTS synchronization or migration task to smoothly switch over the associated services.

    6. Complete the migration

      After your data is migrated and your services are running stably on the PolarDB cluster, you can end the upgrade process. If data synchronization is no longer needed, click Complete Migration.

    7. (Optional) Unsubscribe from or release the RDS instance

      If your services are running stably on the PolarDB cluster and the RDS instance is no longer needed, unsubscribe from or release the RDS instance.

    API operations

    This section outlines the one-click upgrade process. Upgrade steps.

    1. (Optional) Check the IP address whitelist

      If your RDS instance has read-only instances and their IP address whitelists are different from the primary instance's whitelist, merge the whitelists of the read-only instances into the primary instance's whitelist. This ensures that the whitelists are automatically synchronized to the PolarDB cluster.

      Note

      The IP address whitelist of a PolarDB cluster applies to the entire cluster. You cannot configure separate whitelists for individual nodes. Therefore, after the migration is complete, review the IP address whitelist and database account permissions for the PolarDB cluster.

    2. CreateDBCluster - Create a PolarDB cluster

      When you call the Create Cluster API, set the SourceResourceId parameter to the region where the source RDS instance is located, the CreationOption parameter to MigrationFromRDS, and the SourceResourceId parameter to the ID of the source RDS instance. After the call is complete, the system performs operations such as initialization, a pre-check, and full data synchronization. During this process, the status of the cluster is Creating. Please wait.

    3. Query the migration status of the PolarDB cluster

      When the returned MigrationStatus parameter is RDS2PolarDB_SYNCING, it indicates that the system has completed full data synchronization and is now performing incremental synchronization.

      Note

      During logical migration (DTS data synchronization), an error such as Precheck Failed may occur. In this case, the MigrationStatus parameter is PRE_CHECK_FAIL. You must resolve the error based on the Error Message

    4. ModifyDBClusterMigration - Cut over a migration task

      When the DelayedSeconds parameter returned by DescribeDBClusterMigration is less than 60 seconds, you can perform a business switchover. Swap the read/write status of the RDS instance and the PolarDB cluster (set the RDS instance to read-only and the PolarDB cluster to read/write), and change the data replication direction (synchronize new data from the PolarDB cluster to the RDS instance).

      Important

      • If you use switchover with endpoints, carefully read the notes on switchover with endpoints. Note that your services may be interrupted for 1 to 5 minutes during the switchover process.

      • After the migration switchover is complete, if you find any data inconsistencies or other issues, you can call ModifyDBClusterMigration to roll back the migration task and promptly restore the state to what it was before the upgrade. Afterwards, you can also call CloseDBClusterMigration to cancel the migration and restore the state to what it was before the switchover.

    5. (Optional) ModifyDtsJobEndpoint - Modify the source or destination database instance of a DTS job

      If your RDS instance has an associated DTS link (other than a DTS data synchronization link for logical migration in a one-click upgrade process), you can modify (replace) the source or destination database instance of the DTS synchronization or migration task to smoothly switch the associated services.

    6. CloseDBClusterMigration - Complete migration

      After the business data migration is complete and your services are running stably on the PolarDB cluster, you can end the one-click upgrade process if you no longer require data synchronization.

    7. (Optional) Unsubscribe from or release the RDS instance

      If your services are running stably on the PolarDB cluster and the RDS instance is no longer needed, unsubscribe from or release the RDS instance.

    3. Adjust the backup policy

    RDS and PolarDB have different backup policies. After the migration is complete, you can modify the backup policy in the console as needed.

    Related information

    Backup policy description

    The backup policies for RDS and PolarDB are different. The differences are as follows:

    • Regular backup cycle and Backup start time: These settings are the same. By default, PolarDB uses the same regular backup cycle and backup start time as the RDS instance.

    • Backup retention period: The mapping is as follows:

      • If the RDS backup retention period is 14 days or less, the PolarDB Level 1 backup retention period is the same as the RDS backup retention period.

      • If the RDS backup retention period is more than 14 days but no more than 30 days, the PolarDB Level 1 backup retention period is fixed at 14 days. Level 2 backup is also enabled, and the PolarDB Level 2 backup retention period in the same region is fixed at 30 days. If the RDS backup retention period is more than 30 days, PolarDB enables Level 2 backup, and the Level 2 backup retention period in the same region is the same as the RDS backup retention period.

      • If RDS backups are configured for long-term retention, the PolarDB Level 1 backup retention period is fixed at 14 days. Level 2 backup is also enabled for long-term retention.

    • If high-frequency backup is enabled for the RDS instance, it is also enabled for the PolarDB cluster by default. High-frequency backup: The frequency mapping is as follows:

      • If the RDS high-frequency backup interval is 120 minutes or less, the PolarDB high-frequency backup interval is fixed at 120 minutes.

      • If the RDS high-frequency backup interval is more than 120 minutes but no more than 180 minutes, the PolarDB high-frequency backup interval is fixed at 180 minutes.

      • For any other RDS backup interval, the PolarDB high-frequency backup interval is fixed at 240 minutes.

    Switchover with endpoints

    During the upgrade, select the switchover with endpoints feature to automatically swap connection endpoints between the RDS instance and the PolarDB cluster. This lets your applications automatically connect to the PolarDB cluster without any configuration changes.

    Important

    Before you switch over the endpoints, confirm the mapping of connection endpoints between the RDS instance and the PolarDB cluster. This prevents business disruptions.

    Connection endpoint switchover diagram

    The following diagram shows the default mapping for the connection endpoint switchover between an RDS instance and a PolarDB cluster. You can adjust this mapping in the console during the switchover process.

    image
    Note

    The read-only endpoint of an RDS instance includes the read-only endpoint in the database proxy and the connection endpoint of the read-only instance.

    Notes

    • The switchover with endpoints feature does not support IPv6 address switchover.

    • The switchover with endpoints feature only swaps the domain names of the connection endpoints for the RDS instance and the PolarDB cluster. Configurations such as virtual switches (vSwitches) and virtual IP addresses (VIPs) are not swapped.

    • Only connection endpoints that exist on both the RDS instance and the PolarDB cluster can be swapped. By default, a PolarDB cluster creates only a private primary endpoint and a private cluster endpoint. If the RDS instance has more than two connection endpoints, you must create the corresponding connection endpoints on the PolarDB cluster before the switchover. Otherwise, the endpoints will not be swapped.

    • When you use the switchover with endpoints feature, the primary connection endpoint of the RDS instance can be swapped with the primary endpoint or default cluster endpoint of the PolarDB cluster. The database proxy endpoint of the RDS instance can be swapped with the default cluster endpoint and custom endpoints of the PolarDB cluster. You can also choose not to swap them or to swap multiple groups. Because a PolarDB cluster can have up to seven cluster endpoints, you can swap a maximum of seven database proxy endpoints from the RDS instance.

    • Switchover is not currently supported for the cluster read-only endpoint and node direct connection endpoint of RDS Cluster Edition instances.

    • Before you use the switchover with endpoints feature to swap private endpoints, make sure the RDS instance and the PolarDB cluster are in the same VPC. Otherwise, your existing services cannot connect after the switchover.

    • After the incremental synchronization is complete, the status of the PolarDB cluster changes to Running. Before you switch over the endpoints, you can perform operations such as configuring parameters, adding read-only nodes, and adding endpoints.

    • After the connection endpoint domain names are swapped, if you need to log on to the PolarDB cluster by using Data Management (DMS), make sure that you have configured the correct cluster ID or connection string.

    • After the connection endpoint domain names are swapped, DNS resolution cache issues may occur. Before the cache expires, you might be unable to connect to the PolarDB cluster or the PolarDB cluster might support only read operations but not write operations. Flush the DNS cache on your server.

    FAQ

    Why is the memory usage of a PolarDB cluster high during the one-click upgrade process?

    During full data initialization, the InnoDB engine caches data in the innodb_buffer_pool memory buffer pool to speed up read and write operations. This process causes the overall memory usage to increase.

    After the one-click upgrade is complete, adjust the innodb_buffer_pool_size parameter in the console to reduce the memory usage of the buffer pool.