All Products
Search

This Product

    ApsaraDB for MongoDB:Migrate a self-managed MongoDB database to a replica set instance using MongoDB tools

    Document Center

    ApsaraDB for MongoDB:Migrate a self-managed MongoDB database to a replica set instance using MongoDB tools

    Last Updated:Mar 30, 2026

    Use mongodump and mongorestore to perform a full offline migration of a self-managed MongoDB database to an ApsaraDB for MongoDB replica set instance. This approach exports a complete snapshot of your source database and restores it to the destination — no incremental sync occurs after the snapshot is taken.

    mongodump and mongorestore migrate all data present at the time mongodump runs. Writes to the source database after that point are not migrated. To migrate with minimal downtime, use Data Transmission Service (DTS) instead. For more information, see Migrate data from a self-managed MongoDB database that uses the replica set architecture to ApsaraDB for MongoDB by using DTS.

    For an overview of all migration and synchronization options, see Data migration and synchronization.

    How it works

    1. Stop writes to the source database to ensure a consistent snapshot.

    2. Run mongodump to export all databases to a local dump directory.

    3. Configure network access between the source server and the destination replica set instance.

    4. Run mongorestore to import the dump files into the replica set instance.

    5. Verify the migrated data, then switch your application to the destination instance.

    Prerequisites

    Before you begin, make sure you have:

    • mongodump and mongorestore installed at the same version as the self-managed MongoDB database. To install, see Install MongoDB on the MongoDB website.

    • A destination replica set instance with storage capacity greater than the occupied storage space of the self-managed MongoDB database. To upgrade the instance, see Change the configurations of an instance.

    Run mongodump and mongorestore on the source server or a separate server with network access to the source — not in the mongo shell.

    Usage notes

    • Stop all writes to the source database before running mongodump. Any writes after mongodump completes are not migrated.

    • If you have previously run mongodump, move the backup files in the dump directory to another directory and make sure that the dump directory is empty before running it again. If it is not empty, its historical backup files are overwritten the next time you back up a database.

    Step 1: Back up the self-managed MongoDB database

    Run mongodump on the server where the self-managed MongoDB database resides (or on a separate server with network access to the source):

    mongodump --host <mongodb_host> --port <port> -u <username> --authenticationDatabase <database>

    Replace the following placeholders:

    Placeholder Description Example
    <mongodb_host> IP address or hostname of the source server 127.0.0.1
    <port> Service port of the self-managed MongoDB database 27017 (default)
    <username> Database account used to connect to the source test
    <database> Authentication database for the specified account admin

    Example:

    mongodump --host 127.0.0.1 --port 27017 -u test --authenticationDatabase admin

    When the Enter password: prompt appears, enter the database password and press Enter. The password is masked as you type.

    After mongodump finishes, backup files are saved to the dump directory in your current working directory.

    Step 2: Migrate data to the replica set instance

    2.1 Get the primary node connection string

    Get the public or internal connection string of the primary node in the destination replica set instance. For more information, see Overview of replica set instance connections.

    To connect over the Internet, apply for a public endpoint first. For more information, see Apply for a public endpoint for an ApsaraDB for MongoDB instance.

    2.2 Add the source server IP to the whitelist

    Add the IP address of the source server to the whitelist of the destination replica set instance:

    • Internal network: Add the private IP address of the Elastic Compute Service (ECS) instance where the source database resides.

    • Internet: Add the public IP address of the source server.

    For more information, see Configure a whitelist for a replica set instance.

    2.3 Restore backup files to the replica set instance

    Run mongorestore on the source server to import all backup files into the destination instance:

    mongorestore --host <Primary_host> -u <username> --authenticationDatabase <database> <backup_directory>

    Replace the following placeholders:

    Placeholder Description Example
    <Primary_host> Connection string of the primary node, including the port dds-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717
    <username> Database account for the destination instance (initial account: root) test
    <database> Authentication database for the specified account. For the root account, use admin admin
    <backup_directory> Path to the dump directory created in Step 1 dump (default)

    Example:

    mongorestore --host dds-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717 -u test --authenticationDatabase admin dump

    When the Enter password: prompt appears, enter the database password and press Enter. The password is masked as you type.

    Verify the migration

    After mongorestore completes, confirm that your data is present and complete before switching traffic.

    Switch your application

    Update your application's connection string to point to the destination replica set instance. Schedule the switchover during off-peak hours to minimize impact.

    What's next