This topic describes how to migrate a self-managed MongoDB database to ApsaraDB for MongoDB by using mongodump and mongorestore, which are built in MongoDB for data backup and restoration. You can directly install mongodump and mongorestore (or create a MongoDB Atlas database) on an on-premises server or an ECS instance to migrate data from the MongoDB Atlas database to an ApsaraDB for MongoDB instance.

Note An on-premises server is used in the following example.

Precautions

  • mongodump and mongorestore are installed, and their version is consistent with the database version of the MongoDB Atlas database. For more information about the installation procedure, visit Install MongoDB at the MongoDB official website.
  • If the source and destination ApsaraDB for MongoDB instances have different versions or storage engines, make sure that the versions or storage engines are compatible. For more information, see MongoDB versions and storage engines.
  • This process is a full data migration. To ensure data consistency, we recommend that you do not write data to the source databases before you migrate data.
  • If you run the mongodump command, the historical backup files in the dump folder are overwritten. If you have used the mongodump command to back up a MongoDB Atlas database, move the backup files in the dump folder to another directory and make sure that the dump folder is empty.
  • Run the mongodump and mongorestore commands on the servers. Do not run these commands on the mongo shell.

Permissions required for database accounts

DatabaseAccount permission
Source MongoDB Atlas databaseRead permissions on the source database
Destination ApsaraDB for MongoDB instanceRead and write permissions on the destination database

Before you begin

In the ApsaraDB for MongoDB console:

  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 capacity of the ApsaraDB for MongoDB instance must be greater than that of the MongoDB Atlas database.
    • If you migrate data to a sharded cluster instance of ApsaraDB for MongoDB, we recommend that you configure sharding to store data. For more information, see Configure sharding to maximize the performance of shards.
  2. Set the password of the root user for the ApsaraDB for MongoDB instance. For more information, see Reset the password of an account for an ApsaraDB for MongoDB instance.
    Note If you have set the password when you create the instance, skip this step.

On the on-premises server:

  1. Install MongoDB databases. For more information, see Install MongoDB.
    Note
    • This server plays an intermediary role in both data backup and restoration. The server is no longer required after the migration is complete.
    • The available storage space of the partition where the backup directory is located must be greater than the occupied storage space of the source MongoDB Atlas databases.
  2. Add the public IP address of the on-premises server to a whitelist of the ApsaraDB for MongoDB instance. For more information, see Configure a whitelist or an ECS security group for an ApsaraDB for MongoDB instance.

Procedure

  1. Log on to the MongoDB Atlas console.
  2. Add the public IP address of the on-premises server to a whitelist of the MongoDB Atlas database. Configure a whitelist for the MongoDB Atlas database
  3. On the Clusters page, find the target cluster and click its name. Clusters
  4. On the Command Line Tools tab, click COPY next to the mongodump command to copy this command with the connection information of the source MongoDB Atlas databases. Copy the mongodump command with connection information
  5. On the on-premises server, back up the source MongoDB Atlas databases.
    1. On the on-premises server, paste the mongodump command that contains the connection information of the source MongoDB Atlas databases.
    2. Replace <PASSWORD> with the password of the specified user and replace <DATABASE> with the names of the source MongoDB Atlas databases.
    3. Run this command and wait until data backup is complete.
  6. Log on to the ApsaraDB for MongoDB console to obtain the public endpoint of the ApsaraDB for MongoDB instance.
    Note You must manually apply for a public endpoint. For more information, see Apply for a public endpoint for a sharded cluster instance.
  7. On the server, run the following command to import the backup files to an 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 in the replica set instance of ApsaraDB for MongoDB, or the public endpoint of a mongos in the sharded cluster instance of ApsaraDB for MongoDB.
    • <username>: the account used to log on to the ApsaraDB for MongoDB instance. In examples of this topic, the test account is used.
    • <database>: the source database that you want to restore. If the backup files contain data from more than one database, repeat this step to restore all the databases.
    • <database_backupfile_directory>: the directory of the backup files.

    Example:

    Restore data to the mongodbtest database.
    mongorestore --host dds-bp**********-pub.mongodb.rds.aliyuncs.com:3717 --authenticationDatabase admin -u test -d mongodbtest /dump/mongodbtest
    Restore data to the test123 database.
    mongorestore --host dds-bp**********-pub.mongodb.rds.aliyuncs.com:3717 --authenticationDatabase admin -u test -d test123 /dump/test123
  8. When Enter password: is displayed, enter the password of the ApsaraDB for MongoDB instance user and press Enter.

After data restoration is complete, the data of the source MongoDB Atlas database is migrated to the destination ApsaraDB for MongoDB instance.