ApsaraDB for MongoDB:Migrate MongoDB Atlas using MongoDB tools

Usage notes

• The mongodump and mongorestore versions must match the version of your MongoDB Atlas database. For installation steps, see the official Install MongoDB documentation.

• For information about the versions and storage engines supported by ApsaraDB for MongoDB, see Versions and storage engines. Verify compatibility before migrating data across different versions or storage engines.

• This is a full data migration. To ensure data consistency, stop write operations to the source database before starting the migration.

• Running the mongodump command overwrites existing backup files in the dump directory. If you have previously run mongodump on the source database, move the existing files out of the dumpdirectory and make sure that the dumpdirectory is empty.

• Run mongodump and mongorestore on a server where MongoDB is installed, not from within the mongo shell.

Required permissions

Prerequisites

On the ApsaraDB for MongoDB console, complete the following steps:

1. Create an ApsaraDB for MongoDB instance. For more information, see Create a replica set instance or Create a sharded cluster instance.

   Note

   • The storage space of the ApsaraDB for MongoDB instance must exceed that of the MongoDB Atlas instance.

   • To migrate data to a sharded cluster instance, shard the data first. For more information, see Enable sharding.

2. Set a database password for the ApsaraDB for MongoDB instance. For more information, see Reset the password.

   Note

   Skip this step if you set a database password when creating the instance.

On the on-premises server, complete the following steps:

1. Install MongoDB. For more information, see Install MongoDB.

   Note

   • This server acts as a temporary intermediary for the backup and restore process and is no longer needed after the migration completes.

   • The available disk space in the backup directory partition must be larger than the storage space used by the MongoDB Atlas database.

2. Add the public IP address of your on-premises server to the whitelist of the ApsaraDB for MongoDB instance. For more information, see Configure a whitelist.

Migrate MongoDB Atlas data

1. Log in to the MongoDB Atlas console.

2. Add the public IP address of your on-premises server to the IP Access List of the MongoDB Atlas instance. In the left-side navigation pane, click Clusters. On the Security tab, click Network Access, and then click + ADD IP ADDRESS in the upper-right corner. In the Add IP Access List Entry dialog box, enter the public IP address of your on-premises server and click Confirm.

3. On the Clusters page, click the name of your cluster.

4. On the Command Line Tools tab, click COPY next to the mongodump command to copy the command with the connection information for your MongoDB Atlas database.

5. On your on-premises server, back up the MongoDB Atlas database.

   1. Paste the mongodump command that contains the connection information for your MongoDB Atlas database.

   2. Replace <PASSWORD> with your database password and <DATABASE> with the name of the database to back up.

   3. Run the command and wait for the backup to complete.

6. Log in to the ApsaraDB for MongoDB console and get the public endpoint of your ApsaraDB for MongoDB instance.

   • For a replica set instance, get the public endpoint of the primary node. For more information, see Connect to a replica set instance.

   • For a sharded cluster instance, get the public endpoint of any mongos node. For more information, see Connect to a sharded cluster instance.

   Note

   You must manually apply for a public endpoint before this step. For more information, see Apply for a public endpoint.

7. On your on-premises server, run the following command to import data to the ApsaraDB for MongoDB instance.

   mongorestore --host <mongodb_host>:3717 --authenticationDatabase admin -u <username> -d <database> <database_backupfile_directory>

   Note

   • <mongodb_host>: the public endpoint of the primary node of the replica set instance or a mongos node of the sharded cluster instance.

   • <username>: the database account of the ApsaraDB for MongoDB instance. For example, test.

   • <database>: the database to restore. If the backup contains multiple databases, repeat this step for each one.

   • <database_backupfile_directory>: the directory where the database backup file is located.

   Examples:

   Restore the mongodbtest database:

   mongorestore --host dds-bp**********-pub.mongodb.rds.aliyuncs.com:3717 --authenticationDatabase admin -u test -d mongodbtest /dump/mongodbtest

   Restore the test123 database:

   mongorestore --host dds-bp**********-pub.mongodb.rds.aliyuncs.com:3717 --authenticationDatabase admin -u test -d test123 /dump/test123

8. When prompted for Enter password:, enter the password for your ApsaraDB for MongoDB instance and press Enter.

After the restoration completes, the MongoDB Atlas database has been successfully migrated to your ApsaraDB for MongoDB instance.