ApsaraDB for MongoDB:Migrate data from a MongoDB Atlas database to ApsaraDB for MongoDB

Prerequisites

Before you begin, make sure that you have:

• An ApsaraDB for MongoDB instance with available storage at least 10% larger than the total data size in the source MongoDB Atlas database (recommended)

• A MongoDB Atlas database account with the required permissions (see Permissions required)

• An ApsaraDB for MongoDB database account with read and write permissions on the destination database

Limits

• DTS reads from the source and writes to the destination concurrently during full data migration, increasing load on both database servers. Migrate data during off-peak hours to minimize impact.

• DTS cannot migrate data from the admin or local database. The config database is an internal database; migrating it is not recommended.

• If the source and destination MongoDB databases use different versions or storage engines, verify that your applications can run on both. For supported versions and storage engines, see MongoDB versions and storage engines.

• Concurrent writes to the destination database cause the destination storage size to be 5%–10% larger than the source data size.

• The destination ApsaraDB for MongoDB instance must not contain documents with the same _id primary key as documents in the source. Otherwise, data may be lost. If conflicts exist, delete the matching documents from the destination before starting the migration, without affecting your business.

Billing

Migration types

Permissions required

For information about how to create a database account and grant the required permissions on MongoDB Atlas, see db.createUser().

For the ApsaraDB for MongoDB destination instance, see Use DMS to manage database accounts.

Add DTS server IP addresses to the MongoDB Atlas allowlist

DTS requires network access to your MongoDB Atlas database. Complete this step before configuring the migration task.

1. Log on to the MongoDB Atlas console.

2. In the left-side navigation pane, click Network Access.

3. On the IP Whitelist tab, click ADD IP ADDRESS.

4. Add the DTS server IP addresses for the region where your source MongoDB Atlas database resides. For DTS IP address ranges, see Add the CIDR blocks of DTS servers. For MongoDB Atlas instructions, see Add IP Access List Entries.

Configure the migration task (new DTS console)

Configure the migration task (old DTS console)

If you are using the new DTS console, follow Configure the migration task (new DTS console) instead.

1. Purchase a data migration instance. For details, see Purchase a DTS instance.

2. Log on to the DTS console.

   If you are redirected to the Data Management Service (DMS) console, click the icon in the to switch to the previous version of the DTS console.

3. In the left-side navigation pane, click Data Migration.

4. In the upper part of the Migration Tasks page, select the region where the ApsaraDB for MongoDB instance resides.

5. Find the data migration instance and click Configure Migration Task.

6. Configure the source and destination databases.

   Source database

   Parameter	Description
   Task Name	The task name. DTS generates one automatically. Specify a descriptive name for easy identification.
   Instance Type	Select User-Created Database with Public IP Address.
   Instance Region	Not required when Instance Type is User-Created Database with Public IP Address.
   Database Type	Select MongoDB.
   Hostname or IP Address	The endpoint of the PRIMARY node in the MongoDB Atlas database. The following animation shows how to obtain the endpoint.
   Port Number	The service port of the MongoDB Atlas database. Default: 27017.
   Database Name	The authentication database where the database account was created.
   Database Account	The MongoDB Atlas account. For required permissions, see Permissions required.
   Database Password	The password for the database account. After entering the password, click Test Connectivity to verify. A Passed message confirms the connection.
   Encryption	Select SSL-encrypted.

   Destination database

   Parameter	Description
   Instance Type	Select MongoDB Instance.
   Instance Region	The region where the ApsaraDB for MongoDB instance resides.
   MongoDB Instance ID	The ID of the ApsaraDB for MongoDB instance.
   Database Name	The authentication database where the database account was created. Enter admin to use the root account.
   Database Account	The ApsaraDB for MongoDB account. For required permissions, see Permissions required.
   Database Password	The password for the database account. After entering the password, click Test Connectivity to verify.

   

7. Click Set Whitelist and Next. DTS automatically adds its server CIDR blocks to the IP address whitelist of Alibaba Cloud database instances. For self-managed databases hosted on Elastic Compute Service (ECS) instances, DTS adds the CIDR blocks to the ECS security group rules. For databases deployed in data centers or on third-party clouds, add the DTS CIDR blocks manually. For details, see Add the CIDR blocks of DTS servers.

   Warning

   Adding DTS CIDR blocks to your allowlist exposes your database to network access from DTS servers. Before proceeding, review the security implications and take preventive measures: use strong credentials, restrict exposed ports, authenticate API calls, audit whitelist rules regularly, and remove unauthorized CIDR blocks promptly. For private connectivity, use Express Connect, VPN Gateway, or Smart Access Gateway.

8. Select migration types and objects.

   Setting	Description
   Migration types	Select Full Data Migration for a one-time migration. Select Full Data Migration + Incremental Data Migration to keep services online during migration. If you omit Incremental Data Migration, stop writing to the source database during migration to maintain data consistency.
   Objects to migrate	In the Available section, select databases or collections, then click the arrow icon to move them to Selected. DTS cannot migrate the admin, local, or config databases. Objects can be databases, collections, or functions. To rename objects in the destination, use the object name mapping feature. For details, see Object name mapping.
   Retry time for failed connections	How long DTS retries after a connection failure. Default: 12 hours. If DTS reconnects within this window, the task resumes. Note that retry time is billed.

9. Click Precheck.

   DTS runs a precheck before the task can start. If the precheck fails, click the info icon next to a failed item to see the cause. Fix the issue and click Precheck again. You can also ignore non-critical failed items and rerun the precheck.

10. After the precheck passes, click Next.

11. In the Confirm Settings dialog box, configure the Instance Class and select the checkbox to agree to Data Transmission Service (Pay-As-You-Go) Service Terms.

12. Click Buy and Start.

Monitor and stop the migration

What's next

After stopping the migration task, switch your workloads to the destination ApsaraDB for MongoDB instance.