PolarDB allows the seamless upgrade of an ApsaraDB RDS for MySQL instance to a PolarDB for MySQL cluster. During the upgrade process, the system automatically synchronizes the accounts, databases, IP whitelists, and necessary parameter configurations from the RDS instance to the PolarDB cluster. In addition, you have the option to retain the original database endpoints to allow your application to seamlessly connect to the PolarDB cluster without requiring any modifications to the connection settings. This process significantly reduces migration complexity and ensures a smooth transition for business operations.
You can upgrade an RDS instance to a PolarDB cluster of the same or higher version. 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.
NotePolarDB for MySQL 8.0.1 is fully compatible with MySQL Community Edition 8.0.13 and earlier versions. PolarDB for MySQL 8.0.2 is fully compatible with MySQL Community Edition 8.0.18 and earlier versions.
The features provided by PolarDB for MySQL 8.0.1 and 8.0.2 have some differences. For more information, see Features in PolarDB for MySQL 5.6, 5.7, and 8.0.
Migration methods
The upgrade supports two migration methods: physical migration (physical replication) and logical migration (DTS data synchronization. The system automatically selects the appropriate migration method based on the RDS instance's MySQL version, edition, and storage type. You cannot manually change the migration method. The following tables compares the two migration methods.
Comparison item | Physical migration (physical replication) | Logical migration (DTS data synchronization) |
Source instance | ApsaraDB RDS for MySQL 5.6 and 5.7 High-availability Edition instances that use the local SSD storage type. These instances can be upgraded to PolarDB for MySQL clusters of the same version. Note The minor version of the ApsaraDB RDS for MySQL instances must meet the following requirements:
| ApsaraDB RDS for MySQL instances except those that support physical migration. These instances can be upgraded to PolarDB for MySQL clusters of the same or different versions. Note There are no restrictions on minor versions. |
Implementation method | First coplies full data from the RDS instance to the PolarDB cluster, and then maintains incremental synchronization from the RDS instance to the PolarDB cluster. Important During incremental synchronization, all non-InnoDB tables are automatically converted into InnoDB tables. | Creates a data synchronization task by using DTS. The task first synchronizes the schema and full data from the RDS instance to the PolarDB cluster, and then maintains incremental data synchronization from the RDS instance to the PolarDB cluster. Note
|
Whether DTS is required | No. | Yes. |
MySQL version migration | Only supports migration to the same version. | Supports migration to the same or a higher version. |
Upgrade duration | The upgrade must be completed within 30 days. After the 30-day period expires, the system automatically stops the migration process. | The upgrade must be completed within 30 days. After the 30-day period expires, the system automatically stops the migration process. |
Whether cross-region migration is supported | No. | No. |
Whether incremental synchronization is supported | Yes. | Yes. |
Whether newly added databases can be migrated | Yes. | No. Note To synchronize newly added databases, go to the DTS console to modify the synchronization objects and configure the new databases in both forward and reverse tasks. |
Whether schema can be migrated | Yes. | Only databases, tables, views, stored procedures, and functions can be migrated. |
Advantages
Switchover with endpoints is supported. You can select to retain the original database endpoints, which allows the applications to connect to the PolarDB cluster without modifying any connection configurations.
No data is lost during the upgrade process.
Incremental migration is supported.
Online hot migration is supported. During the upgrade process, there is only a single brief interruption, with downtime lasting less than 10 minutes (which occurs when the business is switched over).
If the migration fails or the migration is no longer needed, you can roll back the migration. The rollback can be completed within 10 minutes.
Usage notes
Impacts on the RDS instance
During the upgrade process, specific operations on the RDS instance may be restricted, and some operations may cause brief interruptions or increased load on the RDS instance.
During the upgrade process, you cannot modify instance parameters.
If you select Switch without Endpoints when performing the switchover, your business may be interrupted for 1 to 5 minutes during the switching. If you select Switch without Endpoints, you must quickly modify your application's connection configuration for connecting to the PolarDB cluster.
If you use the logical migration (DTS data synchronization) migration method, follow these guidelines:
Delete the triggers that are created for RDS instance. Otherwise the migration is interrupted.
During initial full data synchronization, do not execute DDL operations that change database or table schema. Otherwise, the data synchronization task fails.
During initial full data synchronization, the read and write resources (such as CPU and IOPS) of the RDS instance and PolarDB cluster are occupied, which may cause increased load on the RDS instance.
Prerequisites
The source RDS instance must meet the following requirements:
Instance basic information:
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 of data tables must be InnoDB or X-Engine.
If the conditions for the physical migration (physical replication) method are not met, the logical migration (DTS data synchronization) method is used. Make sure that the RDS instance meets the following requirements:
No DTS bidirectional synchronization tasks exist. If DTS bidirectional synchronization tasks exist, do not perform the upgrade. Otherwise, data inconsistency may occur during the upgrade.
Delete the triggers that are created for RDS instance. Otherwise the migration is interrupted.
By default, the binary logging feature is enabled for the RDS instance. Make sure that the value of the binlog_row_image parameter is full. Otherwise, an error is returned during the precheck phase and the data synchronization task cannot be started successfully.
For DTS to reliably access the binary log files for incremental data synchronization during the migration process, the RDS instance's binary log files must be retained for at least 7 days. Otherwise, the synchronization task may fail. In extreme cases, data inconsistency or loss may occur. The Service Level Agreement (SLA) of DTS does not cover issues caused by setting the binlog file retention period to less than the required 7 days.
If you want to use the physical migration (physical replication) migration method even when the conditions are not met, make sure that the RDS instance version meets the following conditions:
For ApsaraDB RDS for MySQL 5.6 High-availability Edition instances, the minor version must be 20190815 or later.
For ApsaraDB RDS for MySQL 5.7 High-availability Edition instances, the minor version must be 20200331 or later.
NoteTo view the Minor Version of the RDS instance, go to the page. You can find the minor version information in the Configuration Information section. If it is earlier than the specified version, update it.
If you use physical migration (physical replication), we recommend that you set the retention period of the binary log files to at least 24 hours.
Limits
The upgrade by using the logical migration (DTS data synchronization) migration method is subject to the following limits:
Data inconsistency between the source and destination databases occurs if data from other sources is written to the destination database during the data synchronization. For example, if you use DMS to execute online DDL statements while data from other sources is written to the destination database, data loss may occur in the destination database.
By default, DTS disables FOREIGN KEY constraints for the destination database in a data synchronization task. Therefore, specific operations such as the cascade and delete operations of the source database are not synchronized to the destination database.
SQL statements supported for incremental synchronization:
Operation type
SQL statement
DML
INSERT,UPDATE,DELETEDDL
ALTER TABLE,ALTER VIEWCREATE FUNCTION,CREATE INDEX,CREATE PROCEDURE,CREATE TABLE,CREATE VIEWDROP INDEX,DROP TABLERENAME TABLETRUNCATE TABLE
Key considerations
Migration phase | Description |
Before migration |
|
During migration |
|
Billing
Logical migration (DTS data synchronization) method
When the logical migration (DTS data synchronization) method is used, you are charged for the DTS data synchronization task and the destination PolarDB cluster.
DTS data synchronization task:
During the upgrade process, the system automatically creates a DTS data synchronization task between the RDS instance and the PolarDB cluster. For more information about the billing rules of DTS tasks, see Billing overview.
The destination PolarDB cluster:
When the billing method is pay-as-you-go, you are not charged for the cluster throughout the migration process. You are charged on a pay-as-you-go basis after the following operations:
Migration completed (including the complete migration operation during the upgrade process).
NoteThe migration is complete when the synchronization link between the RDS instance and the PolarDB cluster is interrupted.
Migration must be completed within 30 days. After the 30-day period expires, the migration feature is disabled, and both the RDS instance and the PolarDB cluster return to read-write status, breaking the replication relationship.
Migration stopped (including canceling the migration operation when precheck fails and the canceling the migration operation during the upgrade process).
In this case, the PolarDB cluster is already created even if the upgrade is stopped. Release the cluster if you no longer need it.
If the destination PolarDB cluster is a serverless cluster, the destination cluster starts to be billed when it enters the Running state.
If the destination PolarDB cluster uses the subscription billing method, you need to complete the payment when you create the cluster.
Physical migration (physical replication) method
If the physical migration (physical replication) is used, you are not charged for the data migration process in the upgrade. You are charged only for the destination PolarDB cluster.
If the destination PolarDB cluster uses the pay-as-you-go billing method, you are not charged for the cluster throughout the migration process. You are charged on a pay-as-you-go basis after the following operations:
Migration completed (including the complete migration operation during the upgrade process).
NoteThe migration is complete when the synchronization link between the RDS instance and the PolarDB cluster is interrupted.
Migration must be completed within 30 days. After the 30-day period expires, the migration feature is disabled, and both the RDS instance and the PolarDB cluster return to read-write status,
Migration stopped (including canceling the migration operation when precheck fails and the canceling the migration operation during the upgrade process).
In this case, the PolarDB cluster is already created even if the upgrade is stopped. Release the cluster if you no longer need it.
If the destination PolarDB cluster is a serverless cluster, the destination cluster starts to be billed when it enters the Running state.
If the destination PolarDB cluster uses the subscription billing method, you need to complete the payment when you create the cluster.
Procedure
1. Evaluate the migration
To ensure a smooth migration process and better migration experience, PolarDB provides the migration evaluation feature. This feature allows you to precheck the prerequisites such as the instance status, migration task dependencies, and attributes of the source instance before the upgrade. This way, you can identify the factors that may affect the migration progress and resolve the issue in advance to reduce the processing and resource costs during migration.
2. Perform the upgrade
(Recommended) Console operations
Below is a brief description of the upgrade process. For detailed step-by-step instructions, see Upgrade steps.
(Optional) Check the whitelist configurations
If the whitelists of the primary and read-only nodes of the source RDS instance are different, you must add the whitelists of the read-only nodes to the whitelists of the primary node in advance to ensure that the whitelists of the read-only nodes can be synchronized to the destination PolarDB cluster.
NoteThe whitelist configuration of a PolarDB cluster applies to the entire cluster and does not support individual configuration for each node. Therefore, after migration is complete, we recommend that you review the whitelists and database account permissions of the PolarDB cluster.
Go to the PolarDB cluster buy page, select the Migrate From RDS creation method, and specify the source RDS version and instance to purchase a PolarDB cluster. After the purchase is complete, the system performs initialization, precheck, and full data synchronization operations. During this period, the cluster is in the Creating state. Wait until the creation is complete.
NoteDuring the upgrade process using logical migration (DTS data synchronization), errors such as Precheck Failure may occur. You can address these errors based on the information in the Error Message. After the error is resolved, you can click Continue Migration to continue the upgrade process. If resolving the current error affects your online business, you can choose to click Abandon Migration to end the upgrade process.
The switchover with endpoints feature allows you to retain the original database endpoints, which enables applications to connect to the PolarDB cluster without modifying any connection configurations. However, only endpoints that exist simultaneously in both the RDS instance and the PolarDB cluster can be exchanged.
You can choose whether to add relevant endpoints on the PolarDB cluster based on your actual situation.
Check the SSL encryption status of the endpoints. The SSL encryption status of the RDS instance and PolarDB cluster endpoints must be consistent.
When the Replication Delay of the PolarDB cluster is less than 60 seconds, you can perform business switching. Click Switch Over to exchange the read-write status of the RDS instance and the PolarDB cluster (change the RDS instance to Read-only and the PolarDB cluster to Read/write), and also change the data replication direction (synchronize new data from the PolarDB cluster to the RDS instance).
ImportantIf you select Switchover with Endpoints when performing switchover, carefully read the usage notes for endpoint exchange. Note that your business may be interrupted for 1 to 5 minutes during the switching process.
If data errors occur after the switchover is complete, you can roll back the switchover. This allows you to restore the database and data to the original state before the switchover is performed. You can then select Cancel Migration to restore the status before the migration.
(Optional) Switch over DTS tasks
If the source RDS instance is involved in a DTS task (not a one-click migration task), you can modify the source or destination database of the DTS task for a smooth switchover.
When data migration is complete and the PolarDB cluster runs stably, you can click Complete Migration to end the upgrade process if you no longer need data synchronization.
Release or unsubscribe from an ApsaraDB RDS instance
When your business is running stably on the PolarDB cluster and you no longer need the RDS instance, you can unsubscribe or release the RDS instance.
API operations
Below is a brief description of the upgrade process. For detailed step-by-step instructions, see Upgrade steps and related API documentation.
(Optional) Check the whitelist configurations
If the whitelists of the primary and read-only nodes of the source RDS instance are different, you must add the whitelists of the read-only nodes to the whitelists of the primary node in advance to ensure that the whitelists of the read-only nodes can be synchronized to the destination PolarDB cluster.
NoteThe whitelist configuration of a PolarDB cluster applies to the entire cluster and does not support individual configuration for each node. Therefore, after migration is complete, we recommend that you review the whitelists and database account permissions of the PolarDB cluster.
Call CreateDBCluster to create a PolarDB cluster.
When you call the API to create a PolarDB cluster, set SourceResourceId to the region of the source RDS instance, CreationOption to MigrationFromRDS, and SourceResourceId to the source RDS instance ID. After the call is complete, the system performs initialization, precheck, and full data synchronization operations. During this period, the cluster is in the Creating state. Wait until the creation is complete.
Call DescribeDBClusterMigration to query the PolarDB cluster status.
When the return parameter MigrationStatus is RDS2POLARDB_SYNCING, the system has completed the synchronization of full data and is performing incremental synchronization.
NoteDuring the upgrade process using logical migration (DTS data synchronization), errors such as Precheck Failure (MigrationStatus is PRE_CHECK_FAIL) may occur. You can address these errors based on the information in the Error Message (Comment). After the error is resolved, you can click Continue Migration to continue the upgrade process. If resolving the current error affects your online business, you can choose to click Abandon Migration to end the upgrade process.
Call ModifyDBClusterMigration to perform migration and switchover.
When the return parameter DelayedSeconds of DescribeDBClusterMigration is less than 60 seconds, you can perform switchover to exchange the read-write status of the RDS instance and the PolarDB cluster (change 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).
ImportantIf you select Switchover with Endpoints when performing switchover, carefully read the usage notes for endpoint exchange. Note that your business may be interrupted for 1 to 5 minutes during the switching process.
After migration switching is complete, if you find data anomalies or other issues, you can call ModifyDBClusterMigration to roll back the migration task to quickly restore to the pre-upgrade state. Afterward, you can still choose to call CloseDBClusterMigration to cancel migration and restore to the state before switching.
If data errors occur after the switchover is complete, you can call ModifyDBClusterMigration to roll back the switchover. This allows you to restore the database and data to the original state before the switchover is performed. You can then select CloseDBClusterMigration to cancel the migration to restore the status before the migration.
(Optional) Call ModifyDtsJobEndpoint to modify the source or destination instance of the DTS stask.
If the source RDS instance is involved in a DTS task (not a one-click migration task), you can modify the source or destination database of the DTS task for a smooth switchover.
Call CloseDBClusterMigration to complete the migration.
When data migration is complete and the PolarDB cluster runs stably, you can click Complete Migration to end the upgrade process if you no longer need data synchronization.
Release or unsubscribe from an ApsaraDB RDS instance
When your business is running stably on the PolarDB cluster and you no longer need the RDS instance, you can unsubscribe or release the RDS instance.
3. Adjust the backup policies
The backup policies of the RDS instance and the PolarDB cluster differ in some aspects. After migration is complete, you can modify the backup policies in the console according to your actual situation.
Related information
Backup policies
The backup policies of the RDS instance and the PolarDB cluster differ in some aspects.
The regular backup cycle and start time remain consistent between the RDS instance and the PolarDB cluster. By default, the PolarDB cluster inherits the same backup cycle and start time from the RDS instance.
The backup retention period mappings:
If the retention period of backup files on the RDS instance is 14 days or less, the retention period of level-1 backup files on the PolarDB cluster is the same as that on the RDS instance.
If the retention period of backup files on the RDS instance is between 14 days (exclusive) and 30 days (inclusive), the retention period of level-1 backup files on the PolarDB cluster is fixed to 14 days. The level-2 backup feature is enabled on the PolarDB cluster and the retention period of level-2 backup files in the same region is fixed to 30 days. If the retention period of backup files on the RDS instance is longer than 30 days, the level-2 backup feature is enabled on the PolarDB cluster and the retention period of level-2 backup files in the same region is the same as that on RDS instance.
If RDS backups are retained for a long term, the PolarDB retention period of level-1 backups is fixed to 14 days. Level -2 backups are retained for a long period of time.
If the high-frequency backup feature is enabled on the RDS instance, the high-frequency backup feature is also enabled on the PolarDB cluster by default. The retention periods of high-frequency backup files on the RDS instance and the PolarDB cluster:
If the retention period of high-frequency backup files on the RDS instance is not longer than 120 minutes, the retention period of high-frequency backup files on the PolarDB cluster is fixed to 120 minutes.
If the retention period of high-frequency backup files on the RDS instance is between 120 minutes (exclusive) and 180 minutes (inclusive), the retention period of high-frequency backup files on the PolarDB cluster is fixed to 180 minutes.
If the retention period of high-frequency backup files on the RDS instance is longer than 180 minutes, the retention period of high-frequency backup files on the PolarDB cluster is fixed to 240 minutes.
Switchover with endpoints
The one-click upgrade process supports the address switching feature. When selected, the system will automatically exchange the connection addresses of the RDS instance and the PolarDB cluster, allowing your applications to automatically connect to the PolarDB cluster without any configuration changes.
Diagram
The following illustrates the default connection address switching relationship between an RDS instance and a PolarDB cluster. During the actual switching process, you can adjust the connection address switching relationship in the console.
The read-only endpoints of an RDS instance includes the proxy read-only point and endpoints of read-only instances.
Usage notes
The switchover with endpoints feature does not support IPv6 addresses.
The switchover with endpoints feature exchanges only the endpoints of the RDS instance and the PolarDB cluster and does not exchange the other configurations such as the vSwitches and virtual IP addresses.
Endpoints can be exchanged only if both the source RDS instance and the destination PolarDB cluster have the endpoints. By default, the destination PolarDB cluster has only a private primary endpoint and a private cluster endpoint. If the RDS instance has more than two endpoints, you must create corresponding endpoints on the destination PolarDB cluster if you want to exchange these endpoints.
You can choose to exchange the primary endpoint of the source RDS instance with the primary endpoint or default cluster endpoint of the destination PolarDB cluster. The proxy endpoint of the RDS instance can be exchanged with the default cluster endpoint or custom endpoint of the PolarDB cluster. You can specify whether to perform endpoint switchover and select the endpoint pairs to exchange. A PolarDB cluster can have up to seven cluster endpoints. Therefore, up to seven proxy endpoints of the RDS instance can be exchanged with the cluster endpoints of the PolarDB cluster.
The Cluster Read-only Endpoint and Direct Node Connection Endpoint of an RDS Cluster Edition instance cannot be exchanged.
Before you switch private endpoints, make sure that the source RDS instance and the destination PolarDB cluster belong to the same VPC. Otherwise, the original services cannot be connected after the switchover.
After incremental synchronization is complete, the destination PolarDB cluster enters the Running state. Before exchanging the endpoints, you can configure parameters, add read-only nodes, and add address settings.
If you want to use Data Management (DMS) to log on to the PolarDB cluster after the endpoints are interchanged, make sure that you specify the correct cluster ID and endpoint.
After the endpoints are switched, the original endpoint entries may remain in the Domain Name System (DNS) cache before the entries expire. During this period, you may fail to connect to the PolarDB cluster, or the instance may allow only read operations. To resolve the issue, we recommend that you refresh the DNS cache.