Use Data Transmission Service (DTS) to migrate data from a PolarDB for MySQL cluster to a PolarDB-X 1.0 instance. Run a full migration for a one-time cutover, or combine full and incremental migration to keep data in sync until you are ready to switch over.
Prerequisites
Before you begin, make sure you have:
-
A PolarDB-X 1.0 instance with available storage larger than the total data size of the source PolarDB for MySQL cluster. Select ApsaraDB RDS for MySQL as the storage type when creating the instance. See Create a PolarDB-X 1.0 instance.
-
Databases and tables pre-created in the destination PolarDB-X 1.0 instance. Schema migration is not supported — create the target schema before starting the migration task. See Create a database and Basic SQL operations.
-
(For incremental migration) Binary logging enabled on the source cluster and the
loose_polar_log_binparameter set toon. See Enable binary logging and Modify parameters.
Billing
| Migration type | Task configuration fee | Data transfer fee |
|---|---|---|
| Full data migration | Free | Free |
| Incremental data migration | Charged. See Billing overview. |
Required permissions
| Database | Full data migration | Incremental data migration |
|---|---|---|
| Source PolarDB for MySQL cluster | SELECT | Read and write |
| Destination PolarDB-X 1.0 instance | Read and write | Read and write |
For how to create and authorize a database account:
-
PolarDB for MySQL cluster: Create and manage a database account and Manage the password of a database account.
-
PolarDB-X 1.0 instance: Manage database accounts.
Supported SQL operations for incremental migration
DML operations are supported: INSERT, UPDATE, and DELETE.
Limits
Source database limits
| Limit | Details |
|---|---|
| Outbound bandwidth | The source server must have enough outbound bandwidth. Insufficient bandwidth reduces migration speed. |
| Primary key or unique constraint | Tables to be migrated must have PRIMARY KEY or UNIQUE constraints, with all fields unique. Otherwise, the destination may contain duplicate records. |
| Table-level migration limit | If you select table-level objects and need to rename tables or columns in the destination, a single migration task supports up to 1,000 tables. For more than 1,000 tables, split into multiple tasks or migrate at the database level instead. |
| Binary log retention (incremental migration) | Binary logs on the source must be retained for: incremental migration only — more than 24 hours; full + incremental migration — at least 7 days. After full migration completes, reduce retention to more than 24 hours. If DTS cannot obtain the binary logs, the task fails and data inconsistency or loss may occur. Retention periods shorter than the minimums above are outside the DTS Service Level Agreement (SLA). Enabling binary logging on a PolarDB for MySQL cluster incurs storage charges for binary log files. |
| DDL operations during migration | Do not run DDL operations on the source during schema migration or full data migration. The task fails if schemas change mid-migration. |
| Writes during full-only migration | For full migration only (no incremental), do not write to the source during migration. To support ongoing writes, use full + incremental migration instead. |
Other limits
| Limit | Details |
|---|---|
| Unsupported data types | DTS cannot migrate the following data types: BIT, VARBIT, GEOMETRY, ARRAY, UUID, TSQUERY, TSVECTOR, and TXID_SNAPSHOT. |
| Prefix indexes | Prefix indexes cannot be migrated. If the source contains prefix indexes, the task may fail. |
| Read-only nodes | Read-only nodes of the source PolarDB for MySQL cluster cannot be migrated. |
| Online DDL tools | Do not use online DDL tools such as pt-online-schema-change on migrated objects during migration. The task fails if online DDL operations are performed. |
| Concurrent writes to destination | Do not write data from other sources to the destination during migration. Concurrent writes cause data inconsistency. |
| Server load | Full data migration uses read and write resources on both source and destination, which increases server load. Schedule migrations during off-peak hours. |
| Destination tablespace | Full migration causes fragmentation in destination tables due to concurrent INSERT operations. After migration, the tablespace of the destination is larger than that of the source. |
| Heartbeat table behavior | DTS periodically runs CREATE DATABASE IF NOT EXISTS `test` on the source to advance the binary log file position. This is expected behavior. |
Migrate data
The migration process has eight steps: navigate to the task page, create a task, configure source and destination databases, test connectivity, select objects and configure migration settings, configure advanced settings, run a precheck, and purchase an instance to start the migration.
Step 1: Go to the Data Migration Tasks page
Navigate to the DTS console where you will create and manage migration tasks.
-
Log on to the Data Management (DMS) console.
-
In the top navigation bar, click DTS.
-
In the left-side navigation pane, choose DTS (DTS) > Data Migration.
To go directly to the task page, use the Data Migration Tasks page of the new DTS console and select the target region in the upper-left corner. Console navigation may vary by mode and layout — see Simple mode and Customize the layout and style of the DMS console.
Step 2: Create a migration task
Start configuring a new migration task.
-
From the drop-down list next to Data Migration Tasks, select the region where the migration instance resides.
-
Click Create Task.
-
(Optional) Click New Configuration Page in the upper-right corner to switch to the new configuration UI.
Skip this step if Back to Previous Version is already displayed — you are already on the new configuration page. The new configuration page is recommended.
Step 3: Configure source and destination databases
Enter the connection details for both the source PolarDB for MySQL cluster and the destination PolarDB-X 1.0 instance.
| Section | Parameter | Description |
|---|---|---|
| N/A | Task Name | A descriptive name for the task. DTS assigns a default name — keep it or replace it with a meaningful name. Task names do not need to be unique. |
| Source Database | Select a DMS database instance. | Select an existing instance to auto-populate parameters, or leave blank to configure manually. To register a new database: in the DMS console, click Create Template; in the DTS console, use the Database Connections page. See Register an Alibaba Cloud database instance and Manage database connections. |
| Database Type | Select PolarDB for MySQL. | |
| Access Method | Select Alibaba Cloud Instance. | |
| Instance Region | The region of the source PolarDB for MySQL cluster. | |
| Replicate Data Across Alibaba Cloud Accounts | Select No if the source and destination are in the same Alibaba Cloud account. | |
| PolarDB Cluster ID | The ID of the source PolarDB for MySQL cluster. | |
| Database Account | The database account for the source cluster. See Required permissions. | |
| Database Password | The password for the database account. | |
| Encryption | Whether to encrypt the connection. See Configure SSL encryption. | |
| Destination Database | Select a DMS database instance. | Same as the source — select an existing instance or configure manually. |
| Database Type | Select PolarDB-X 1.0. | |
| Access Method | Select Alibaba Cloud Instance. | |
| Instance Region | The region of the destination PolarDB-X 1.0 instance. | |
| Instance ID | The ID of the destination PolarDB-X 1.0 instance. | |
| Database Account | The database account for the destination instance. See Required permissions. | |
| Database Password | The password for the database account. |
Step 4: Test connectivity and authorize DTS access
Click Test Connectivity and Proceed at the bottom of the page.
DTS automatically adds its CIDR blocks to the IP whitelist of Alibaba Cloud database instances or to the security group rules of Elastic Compute Service (ECS) instances hosting self-managed databases. For self-managed databases on multiple ECS instances, add the CIDR blocks to each instance manually. For on-premises or third-party cloud databases, add the CIDR blocks manually to the database IP whitelist. See CIDR blocks of DTS servers.
Adding DTS CIDR blocks to whitelists or security group rules introduces security exposure. Before proceeding, take preventive measures: use strong credentials, limit exposed ports, authenticate API calls, and audit whitelist rules regularly. Alternatively, connect the database to DTS over Express Connect, VPN Gateway, or Smart Access Gateway.
Step 5: Select objects and configure migration settings
Select which databases or tables to migrate and choose the migration type.
On the Select Objects page, configure the following parameters.
| Parameter | Description |
|---|---|
| Migration Types | Select Full Data Migration for a one-time migration. Select both Full Data Migration and Incremental Data Migration to keep the destination in sync and minimize downtime during the migration window. If you select full migration only, do not write to the source during migration. |
| Processing Mode of Conflicting Tables | Precheck and Report Errors: the precheck fails if source table names match destination table names. Use the object name mapping feature to rename conflicting tables. Ignore Errors and Proceed: skips the precheck for name conflicts. Rows with matching primary keys are skipped; schema mismatches may cause partial migration or task failure. Use with caution. |
| Capitalization of Object Names in Destination Instance | Controls capitalization of database, table, and column names in the destination. Default is DTS default policy. See Specify the capitalization of object names in the destination instance. |
| Source Objects | Select objects to migrate, then click the arrow icon to add them to Selected Objects. Only tables can be selected as migration objects. |
| Selected Objects | To rename a single object, right-click it. To rename multiple objects, click Batch Edit. To filter rows, right-click a table and set filter conditions. See Map object names and Set filter conditions. Renaming an object may cause dependent objects to fail migration. |
Step 6: Configure advanced settings
Click Next: Advanced Settings and configure the following parameters to control task behavior, performance throttling, and alerting.
| Parameter | Description |
|---|---|
| Dedicated Cluster for Task Scheduling | DTS schedules tasks to a shared cluster by default. To improve stability, purchase a dedicated cluster. See What is a DTS dedicated cluster. |
| Retry Time for Failed Connections | How long DTS retries when the source or destination becomes unreachable after the task starts. Valid values: 10–1,440 minutes. Default: 720 minutes. Set to at least 30 minutes. If multiple tasks share the same database, the most recently set value takes precedence. DTS charges during retry attempts. |
| Retry Time for Other Issues | How long DTS retries failed DDL or DML operations. Valid values: 1–1,440 minutes. Default: 10 minutes. Set to at least 10 minutes. Must be smaller than Retry Time for Failed Connections. |
| Enable Throttling for Full Data Migration | Limit the read/write load on source and destination during full migration by setting Queries per second (QPS) to the source database, RPS of Full Data Migration, and Data migration speed for full migration (MB/s). Available only when Full Data Migration is selected. |
| Enable Throttling for Incremental Data Migration | Limit load during incremental migration by setting RPS of Incremental Data Migration and Data migration speed for incremental migration (MB/s). Available only when Incremental Data Migration is selected. |
| Environment Tag | Tag to identify the DTS instance. Optional. |
| Whether to delete SQL operations on heartbeat tables of forward and reverse tasks | Controls whether DTS writes heartbeat SQL to the source database. Yes: does not write SQL operations on heartbeat tables. In this case, latency of the DTS instance may be displayed. No: DTS writes heartbeat SQL, which may affect physical backup and cloning of the source database. |
| Configure ETL | Whether to configure extract, transform, and load (ETL) processing. Yes: opens a code editor for data transformation statements. See Configure ETL in a data migration or data synchronization task. No: no ETL processing. |
| Monitoring and Alerting | Whether to receive alerts when the task fails or latency exceeds a threshold. Yes: configure the alert threshold and notification settings. See Configure monitoring and alerting when you create a DTS task. No: no alerts. |
Step 7: Save settings and run a precheck
DTS validates the configuration before starting the migration. The task cannot start until the precheck passes.
Click Next: Save Task Settings and Precheck.
To preview the API parameters for this configuration before saving, hover over Next: Save Task Settings and Precheck and click Preview OpenAPI parameters.
-
If a check item fails, click View Details next to the failed item. Fix the issue, then click Precheck Again.
-
If a check item generates an alert that you can safely ignore, click Confirm Alert Details, then click Ignore > OK > Precheck Again. Ignored alerts may result in data inconsistency.
Wait until the success rate reaches 100%, then click Next: Purchase Instance.
Step 8: Purchase an instance and start the migration
Select an instance class to determine migration speed, then start the task.
-
On the Purchase Instance page, configure the following parameters.
Section Parameter Description New Instance Class Resource Group Settings The resource group for the migration instance. Default: default resource group. See What is Resource Management?. Instance Class The migration instance class, which determines migration speed. See Instance classes of data migration instances. -
Select the check box to agree to Data Transmission Service (Pay-as-you-go) Service Terms.
-
Click Buy and Start to start the migration task. Track progress in the task list.