Use mongodump and mongorestore to perform a full offline migration from a self-managed MongoDB database to an ApsaraDB for MongoDB sharded cluster instance. This approach requires a write freeze during migration and suits environments where brief downtime is acceptable.
For migrations that require continuous writes and zero downtime, use Data Transmission Service (DTS) instead. See Migrate data from a self-managed MongoDB database that uses the sharded cluster architecture to ApsaraDB for MongoDB by using DTS.
Prerequisites
Before you begin, ensure that you have:
mongodump and mongorestore installed at the same version as your self-managed MongoDB databases. See Install MongoDB for installation instructions.
A destination sharded cluster instance with storage capacity larger than the data size of your self-managed databases. If the capacity is insufficient, upgrade the instance before proceeding.
mongodump and mongorestore can run on the same server as your self-managed databases or on a separate server.
Migration constraints
This is a full data migration. Stop all writes to the self-managed databases before migrating to ensure data consistency.
If the
dumpfolder already contains files from a previous run, move them to another directory first. mongodump overwrites existing files in thedumpfolder.Run mongodump and mongorestore from a server shell — not from the mongo shell.
Step 1: Back up the self-managed MongoDB databases
On the server where your self-managed databases reside, run:
mongodump --host <mongodb_host> --port <port> -u <username> --authenticationDatabase <database>| Parameter | Description | Default |
|---|---|---|
<mongodb_host> | Address of the server where the self-managed databases reside | 127.0.0.1 |
<port> | Service port of the self-managed databases | 27017 |
<username> | Account used to connect to the database | — |
<database> | Authentication database for the account | — |
Example:
mongodump --host 127.0.0.1 --port 27017 -u test --authenticationDatabase adminWhen prompted with Enter password:, enter the database password and press Enter. The backup runs and saves data to the dump folder in your current directory.
Step 2: (Optional) Configure sharding
Without sharding configured, all data is written to the primary shard only, leaving other shards unused. To distribute data across shards, configure sharding before or after migration.
Create the required databases and collections in the destination sharded cluster instance before migrating data. You can configure sharding before or after migration.
For configuration steps, see Configure sharding to maximize the performance of shards.
Step 3: Restore data to the destination sharded cluster instance
3.1 Get the mongos connection string
Get the public or internal connection string of a mongos node in your destination sharded cluster instance. See Overview of sharded cluster instance connections.
Public endpoints are not enabled by default. To use a public connection, first apply for a public endpoint.
3.2 Add your server's IP address to the whitelist
Add the IP address of the server running mongorestore to the whitelist of your destination sharded cluster instance. See Configure a whitelist for an instance.
Internal network: Add the private IP address of the ECS instance where your self-managed databases reside.
Internet: Add the public IP address of the server where your self-managed databases reside.
3.3 Restore the backup to the destination instance
Run the following command to restore all backup files to the destination sharded cluster instance:
mongorestore --host <Mongos_host> -u <username> --authenticationDatabase <database> <backup_directory>| Parameter | Description | Default |
|---|---|---|
<Mongos_host> | Connection string of any mongos node in the ApsaraDB for MongoDB instance | — |
<username> | Account used to connect to the destination instance (the initial account is root) | — |
<database> | Authentication database for the account (use admin for the root account) | — |
<backup_directory> | Directory containing the backup files | dump |
Example (account: test, authentication database: admin):
mongorestore --host s-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717 -u test --authenticationDatabase admin dumpWhen prompted with Enter password:, enter the password. The characters are masked as you type.
What's next
After the restore completes, switch your application traffic to the destination sharded cluster instance. Schedule the switchover during off-peak hours to minimize impact on your users.
For an overview of available migration and synchronization options, see Data migration and synchronization.