Migrate a self-managed database to a standalone instance using MongoDB tools - ApsaraDB for MongoDB

For zero-downtime migrations of self-managed, standalone MongoDB databases to the cloud, use Data Transmission Service (DTS). For more information, see Full migration from ApsaraDB for MongoDB (standalone architecture) to ApsaraDB for MongoDB (all architectures).

For information about solutions for other data migration or synchronization scenarios, see Data migration and synchronization.

Prerequisites

Ensure that the versions of the mongodump and mongorestore tools match the version of your self-managed MongoDB database. For installation instructions, see the official Install MongoDB documentation.

Note
Alternatively, you can run the mongodump and mongorestore commands on the server that hosts your self-managed database without installing them separately.
To ensure compatibility, your self-managed MongoDB database must be version 3.0 or later.

Note
For information about the storage engines supported by ApsaraDB for MongoDB, see Versions and storage engines. If you are migrating across different versions or storage engines, verify compatibility before you start.
The destination standalone instance must have more storage capacity than the space used by the self-managed database. If the storage capacity is insufficient, you can increase it. For more information, see Modify instance configuration.

Usage notes

This process performs a full data migration. To ensure data consistency, stop all related services and write operations on your self-managed database before starting the migration.
If you have previously backed up the database using the mongodump command, move the backup files from the dump folder to another directory and ensure that the dump folder is empty. Otherwise, the existing backup files will be overwritten.
Run the mongodump and mongorestore commands on the server that hosts your self-managed MongoDB database, not from within the mongo shell environment.

Step 1: Back up the self-managed database

On the server that hosts your self-managed database, run the following command to back up all databases.
```
mongodump --host <mongodb_host> --port <port>  -u <username>  --authenticationDatabase  <database>
```
Note
- <mongodb_host>: The server address of your self-managed MongoDB database. You can use 127.0.0.1 if you are running the command on the database server.
- <port>: The port number of the database service. The default value is 27017.
- <username>: The account for the self-managed database, such as test.
- <database>: The authentication database to which the user account belongs.
Example:
```
mongodump --host 127.0.0.1 --port 27017 -u test --authenticationDatabase admin
```
When the CLI prompts Enter password:, enter the database account password and press Enter to begin the backup.

Note
Password characters are hidden when you enter them.

After the backup is complete, the data from your self-managed database is saved to the dump folder in the current directory.

Step 2: Migrate data to Alibaba Cloud

Obtain the primary node endpoint of the ApsaraDB for MongoDB instance.

Log on to the ApsaraDB for MongoDB console.
In the upper-left corner of the page, select the region where the instance is located.
In the left-side navigation pane, click Replica Set Instances.
Find the target instance and click the instance ID.

In the left-side navigation pane, click Database Connections to view connection details.

On the connection information page, the VPC and public connection sections display the endpoint for the primary node (for example, dds-<instanceID>.mongodb.rds.aliyuncs.com:3717, where public endpoints include the -pub suffix) and a ConnectionStringURI (for example, mongodb://root:****@<endpoint>/admin). Use the primary node's endpoint for the migration.

Table 1. Connection endpoints
Endpoint type	Description	Scenario
VPC endpoint	A Virtual Private Cloud (VPC) is an isolated network environment that provides higher security and performance than the classic network.	Use this when your self-managed MongoDB database is deployed on an ECS instance. Note The ECS instance and the ApsaraDB for MongoDB instance must be in the same region and VPC.
public endpoint	For security reasons, a public endpoint is not enabled by default. You must apply for one. For more information, see Apply for a public endpoint.	Use this when your self-managed MongoDB database is deployed on an on-premises server.

Add the IP address of your self-managed database's server to the whitelist of the ApsaraDB for MongoDB instance. For more information, see Configure a whitelist.
Note
- If you connect to the ApsaraDB for MongoDB instance over a VPC, add the private IP address of the ECS instance that hosts your self-managed database to the whitelist.
- If you connect to the ApsaraDB for MongoDB instance using a public endpoint, add the public IP address of the on-premises server that hosts your self-managed database to the whitelist.
On the server that hosts your self-managed database, run the following command to restore the data to the ApsaraDB for MongoDB instance.
```
mongorestore --host <Primary_host>  -u <username> --authenticationDatabase <database> <Backup directory>
```
Note
- <Primary_host>: The primary node endpoint for your ApsaraDB for MongoDB instance.
- <username>: The database account for the ApsaraDB for MongoDB instance. The initial account is root.
- <database>: The authentication database. If you use the root account, this database is admin.
- <Backup directory>: The directory where the backup files are stored. The default directory is dump.
Example:

The database account is test, and the authentication database is admin.
```
mongorestore --host dds-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717 -u test --authenticationDatabase admin dump
```
When the CLI prompts Enter password:, enter the password for the ApsaraDB for MongoDB database account and press Enter. The data restoration process starts.
Note
- Password characters are hidden when you enter them.
- If you have forgotten the password for the root account, you can reset it. For more information, see Reset a password.

After the data migration is complete, switch your services to the ApsaraDB for MongoDB instance when ready.

Next steps

After migrating the database, connect to the ApsaraDB for MongoDB instance to manage databases and accounts.