Introduction
Migrating from a self-managed MongoDB database to Amazon DocumentDB requires careful planning, data extraction, secure file transfer, namespace mapping, restoration, and validation.
This guide explains how to migrate the sourcedb database from a self-managed MongoDB server to an Amazon DocumentDB cluster, using destinationdb as the destination database..
The migration uses MongoDB Database Tools (mongodump and mongorestore), rsync for transferring backup files, TLS for encrypted connectivity, and a dry-run restore to validate the migration command before making changes.
What Is Amazon DocumentDB?
Amazon DocumentDB is a fully managed document database service from Amazon Web Services that supports MongoDB-compatible APIs.
It allows developers to use many familiar MongoDB drivers, tools, and document-oriented data structures while AWS manages infrastructure-related operations.
Amazon DocumentDB provides capabilities such as managed backups, high availability, monitoring, and storage management.
However, Amazon DocumentDB is not identical to MongoDB. Feature compatibility, supported operators, index behavior, and application functionality can differ depending on the target engine version.
AWS maintains an official compatibility reference that should be reviewed before migration
Why Migrate MongoDB to Amazon DocumentDB?
Organizations may consider migrating MongoDB to Amazon DocumentDB to simplify database operations and take advantage of AWS-managed infrastructure.
Potential benefits include:
-
Reduced infrastructure management: Less responsibility for manually maintaining database infrastructure.
-
High availability: Managed deployment options with replication and failover capabilities.
-
Automated backups: AWS-managed backup and recovery functionality.
-
AWS integration: Connectivity with services such as Amazon EC2, AWS IAM, Amazon CloudWatch, and AWS networking.
-
Operational scalability: Managed infrastructure options to accommodate changing workloads.
These benefits should be evaluated against application compatibility, performance requirements, and projected costs.
Migration overview
Source environment
- Database: sourcedb
- MongoDB host: localhost
- Port: 27017
- Backup directory: /usr/local/src/migrate/dump/
Destination environment
- Amazon DocumentDB cluster: destination-db
- Destination database: destinationdb
- Backup staging directory: /var/www/mongorestore/dump/
- TLS certificate bundle: /root/global-bundle.pem
Prerequisites
Before starting the migration, confirm the following.
Source MongoDB
- The source MongoDB instance is running.
- The migration account has permission to read the required database and collections.
- MongoDB Database Tools are installed.
Destination server
- SSH access to the source server is available.
- The destination server can reach the Amazon DocumentDB cluster over TCP port 27017.
- The destination server has the appropriate DocumentDB CA bundle.
- MongoDB Database Tools are compatible with the target Amazon DocumentDB environment.
Create a MongoDB dump on the source server
Log in to the source MongoDB server and execute the following command.
| mongodump –host=”localhost” –port=27017 –username=”sourcedbuser” –password –authenticationDatabase=”sourcedb” –db=”sourcedb” –out=”/usr/local/src/migrate/dump” |
The command prompts for the password.
Explanation of the parameters
| Parameter | Purpose |
| –host | MongoDB server hostname |
| –port | MongoDB connection port |
| –username | Source database username |
| –password | Prompts for the password |
| –authenticationDatabase | Database where the user authenticates |
| –db | Database to back up |
| –out | Directory where dump files are written |
Expected directory structure
After a successful dump, the directory should resemble:
/usr/local/src/migrate/
└── dump/
└── sourcedb/
├── collection1.bson
├── collection1.metadata.json
├── collection2.bson
├── collection2.metadata.json
└── …
Actual filenames depend on the collections in the database. The BSON files contain the document data, while the metadata files can contain collection options and index definitions.
Transfer the dump to the destination server
On the destination server, ensure the target directory exists and use rsync to transfer the MongoDB backup securely from the source server.
command:
| rsync -avz root@sourceip:/usr/local/src/migrate/dump/ /var/www/mongorestore/dump/ |
Prepare the Amazon DocumentDB destination
Verify the TLS certificate bundle. Confirm that the certificate bundle exists:
| ls -l /root/global-bundle.pem |
Use the current AWS-provided CA bundle appropriate for Amazon DocumentDB. Keep the bundle readable by the migration account and do not disable certificate verification to bypass TLS errors.
Verify database authentication
Use the target administrator account and a TLS-enabled connection:
| mongosh –host=”destination-db.cluster-cbpxrmfy65hz.ap-south-1.docdb.amazonaws.com:27017” –username=”admin00000″ –password –authenticationDatabase=”admin” –tls –tlsCAFile=”/root/global-bundle.pem” –retryWrites=false |
Enter the password when prompted. After connecting, check the available databases and confirm that the account has the permissions required for the restore.
Map the source database to the destination database
The source database is named sourcedb, while the destination database must be named destinationdb. The following namespace mapping handles that change:
| –nsFrom=”sourcedb.*”
–nsTo=”destinationdb.*” |
The wildcard preserves each collection name while changing its database name. This mapping does not rename the individual collections or transform document fields. It only changes the namespaces used by the restore operation.
Perform a dry-run restore
Before modifying production data, execute a dry run on destination server.
| mongorestore –host=”destination-db.cluster-cbpxrmfy65hz.ap-south-1.docdb.amazonaws.com:27017” –username=”admin00000″ –password –tls –tlsCAFile=”/root/global-bundle.pem” –authenticationDatabase=”admin” –retryWrites=false –nsFrom=”sourcedb.*” –nsTo=”destinationdb.*” –drop –dryRun “/var/www/mongorestore/dump/” |
Enter the destination password when prompted. A dry run checks and reports the restore plan without importing the documents. The –drop option is included to document the intended final restore behavior, but it does not actually drop collections during a supported dry run.
Restore the data into Amazon DocumentDB
Once the dry run, backup integrity checks, target connectivity, and change-control approvals are complete, run the actual restore. The following command omits –dryRun, so it will perform real changes:
| mongorestore –host=”destination-db.cluster-cbpxrmfy65hz.ap-south-1.docdb.amazonaws.com:27017” –username=”admin00000″ –password –tls –tlsCAFile=”/root/global-bundle.pem” –authenticationDatabase=”admin” –retryWrites=false –nsFrom=”sourcedb.*” –nsTo=”destinationdb.*” –drop “/var/www/mongorestore/dump/” |
Enter the password when prompted.
Validate the restored database
A completed mongorestore command does not by itself prove that the migration is correct. Validate the result at multiple levels.
Verify the destination database
Connect to Amazon DocumentDB using mongosh:
| mongosh –host=”destination-db.cluster-cbpxrmfy65hz.ap-south-1.docdb.amazonaws.com:27017” –username=”admin00000″ –password –authenticationDatabase=”admin” –tls –tlsCAFile=”/root/global-bundle.pem” –retryWrites=false |
Then run:
| show dbs
use destinationdb show collections |
Confirm that the expected collections exist.
Validate application functionality
After database-level checks, verify the application against the destination database.
Test:
- Database authentication and connection pooling.
- Reads and writes for representative application workflows.
- Critical queries and aggregation pipelines.
- Background jobs, scheduled tasks, and event processing.
- Error logs and application health checks.
Keep the source available and retain a rollback plan until the destination has passed the required validation.
Conclusion
Migrating MongoDB to Amazon DocumentDB using mongodump, rsync, and mongorestore is a practical approach for controlled migrations.
The essential stages are to create a reliable source backup, transfer it securely, map sourcedb to destinationdb, validate the restore plan, execute the restore, and verify data integrity and application compatibility.
Need Expert Help Migrating MongoDB to Amazon DocumentDB?
A successful MongoDB migration requires careful planning, compatibility checks, secure data transfer, and thorough validation. Businesses planning to move their databases to AWS can work with Skynats for migration planning, cloud infrastructure management, and post-migration support.
