This guide covers migrating a self-managed MongoDB database to ApsaraDB for MongoDB using mongodump and mongorestore. The self-managed database can run on an on-premises device or an Elastic Compute Service (ECS) instance.
mongodump and mongorestore perform a full data migration with no support for incremental sync. To avoid service disruption, we recommend that you use Data Transmission Service (DTS) to migrate a self-managed MongoDB database that uses the standalone architecture to ApsaraDB for MongoDB.
For an overview of all migration and synchronization options, see Data migration and synchronization.
Prerequisites
Before you begin, ensure that you have:
-
mongodump and mongorestore installed on a different server from the self-managed MongoDB database, but at the same version as the source database. See Install MongoDB for installation instructions. You can also run the mongodump and mongorestore commands on the server where the self-managed MongoDB database resides.
-
A source database running MongoDB 3.0 or later. If the source and destination run different versions or storage engines, verify compatibility first. See MongoDB versions and storage engines
-
A destination ApsaraDB for MongoDB standalone instance with enough storage for all source data. To expand storage, see Change the configurations of an instance
Considerations
Downtime required
This is a full data migration. Any writes to the source database after mongodump completes are not migrated. To ensure data consistency, we recommend that you stop writing data to the self-managed MongoDB database before you migrate data.
Existing backup files
If you have previously run mongodump, it writes output to a dump folder in the current directory. Move any existing files out of that folder before running mongodump again, or the historical backup files will be overwritten.
Where to run the commands
Run mongodump and mongorestore directly on the server, not inside the mongo shell.
Step 1: Back up the source database
Run the following command on the server where the self-managed MongoDB database resides:
mongodump --host <mongodb-host> --port <port> -u <username> --authenticationDatabase <auth-db>Replace the placeholders with your values:
| Placeholder | Description | Example |
|---|---|---|
<mongodb-host> |
Address of the server running the self-managed MongoDB database | 127.0.0.1 |
<port> |
Service port of the source database | 27017 (default) |
<username> |
Account used to log in to the source database | test |
<auth-db> |
Database that holds the credentials for the specified username | admin |
Example:
mongodump --host 127.0.0.1 --port 27017 -u test --authenticationDatabase adminWhen prompted with Enter password, type the account password and press Enter. The characters are masked as you type.
When the command completes, the backup is saved to the dump folder in the directory where you ran the command.
Step 2: Restore data to the destination instance
Get the endpoint of the destination instance
-
Log in to the ApsaraDB for MongoDB console.
-
In the upper-left corner, select the region where the instance is deployed.
-
In the left-side navigation pane, click Replica Set Instances.
-
Click the instance ID of the destination instance.
-
In the left-side navigation pane, click Database Connections to view the connection details.
Choose the endpoint type based on your network setup:
| Endpoint type | When to use |
|---|---|
| VPC endpoint | The source database runs on an ECS instance in the same region and Virtual Private Cloud (VPC) as the ApsaraDB for MongoDB instance |
| Public endpoint | The source database runs on an on-premises device. Public endpoints are not enabled by default — see Apply for a public endpoint for a standalone ApsaraDB for MongoDB instance |
Add the source server IP address to the whitelist
Add the IP address of the server running the source database to the ApsaraDB for MongoDB instance whitelist. See Configure a whitelist for an instance.
-
VPC connection: add the internal IP address of the ECS instance
-
Public connection: add the public IP address of the on-premises server
Run mongorestore
On the server where the source database resides, run:
mongorestore --host <primary-endpoint> -u <username> --authenticationDatabase <auth-db> <backup-dir>Replace the placeholders with your values:
| Placeholder | Description | Example |
|---|---|---|
<primary-endpoint> |
Endpoint of the primary node, including the port | dds-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717 |
<username> |
Database account of the ApsaraDB for MongoDB instance. The initial account is root |
test |
<auth-db> |
Database that holds the credentials for the specified username. For root, use admin |
admin |
<backup-dir> |
Path to the backup directory created by mongodump | dump (default) |
Example:
mongorestore --host dds-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717 -u test --authenticationDatabase admin dumpWhen prompted with Enter password, type the account password and press Enter. The characters are masked as you type.
If you forget the root password, reset it before proceeding. See (Optional) Reset a password.
When mongorestore finishes, schedule a maintenance window during off-peak hours to switch your application traffic to the ApsaraDB for MongoDB instance.
What's next
After migration, connect to the instance and set up user access: