Migrate MongoDB to Azure Cosmos DB for MongoDB vCore offline using MongoDB native tools
Article
APPLIES TO:
MongoDB vCore
In this tutorial, you use MongoDB native tools to perform an offline (one-time) migration of a database from an on-premises or cloud instance of MongoDB to Azure Cosmos DB for MongoDB vCore. The MongoDB native tools are a set of binaries that facilitate data manipulation on an existing MongoDB instance. The focus of this doc is on migrating data out of a MongoDB instance using mongoexport/mongoimport or mongodump/mongorestore. Since the native tools connect to MongoDB using connection strings, you can run the tools anywhere. The native tools can be the simplest solution for small datasets where total migration time isn't a concern.
Prerequisites
An existing Azure Cosmos DB for MongoDB vCore cluster.
Prior to starting the migration, make sure you have prepared your Azure Cosmos DB for MongoDB vCore account and your existing MongoDB instance for migration.
MongoDB instance (source)
Complete the premigration assessment to determine if there are a list of incompatibilities and warnings between your source instance and target account.
Ensure that your MongoDB native tools match the same version as the existing (source) MongoDB instance.
If your MongoDB instance has a different version than Azure Cosmos DB for MongoDB vCore, then install both MongoDB native tool versions and use the appropriate tool version for MongoDB and Azure Cosmos DB for MongoDB vCore, respectively.
Add a user with readWrite permissions, unless one already exists. You eventually use this credential with the mongoexport and mongodump tools.
We recommend running these tools within the same network as the MongoDB instance to avoid further firewall issues.
Choose the proper MongoDB native tool
There are some high-level considerations when choosing the right MongoDB native tool for your offline migration.
Perform the migration
Migrate a collection from the source MongoDB instance to the target Azure Cosmos DB for MongoDB vCore account using your preferred native tool. For more information on selecting a tool, see native MongoDB tools
Tip
If you simply have a small JSON file that you want to import into Azure Cosmos DB for MongoDB vCore, the mongoimport tool is a quick solution for ingesting the data.
Observe that the tool created a directory with the native BSON data dumped. The files and folders are organized into a resource hierarchy based on the database and collection names. Each database is a folder and each collection is a .bson file.
Restore the contents of any specific collection into an Azure Cosmos DB for MongoDB vCore account by specifying the collection's specific BSON file. The filename is constructed using this syntax: <dump-directory>/<database-name>/<collection-name>.bson.
You can also restore a specific collection or collections from the dump-directory /directory. For example, the following operation restores a single collection from corresponding data files in the dump-directory / directory. mongorestore --nsInclude=test.purchaseorders <dump-directory>/
Monitor the terminal output from mongoimport. The output prints lines of text to the terminal with updates on the restore operation's status.