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

Prepare

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.
  • Azure Cosmos DB for MongoDB vCore (target)

Tip

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.

  1. To export the data from the source MongoDB instance, open a terminal and use any of three methods listed here.

    • Specify the --host, --username, and --password arguments to connect to and export JSON records.

      mongoexport \
    --host <hostname><:port> \
    --username <username> \
    --password <password> \
    --db <database-name> \
    --collection <collection-name> \
    --out <filename>.json

    • Export a subset of the MongoDB data by adding a --query argument. This argument ensures that the tool only exports documents that match the filter.

      mongoexport \
    --host <hostname><:port> \
    --username <username> \
    --password <password> \
    --db <database-name> \
    --collection <collection-name> \
    --query '{ "quantity": { "$gte": 15 } }' \
    --out <filename>.json

    • Export data from Azure Cosmos DB for MongoDB vCore.

      mongoexport \
    --uri <target-connection-string>
    --db <database-name> \
    --collection <collection-name> \
    --query '{ "quantity": { "$gte": 15 } }' \
    --out <filename>.json

  2. Import the previously exported file into the target Azure Cosmos DB for MongoDB vCore account.

    mongoimport \
    --file <filename>.json \
    --type json \
    --db <database-name> \
    --collection <collection-name> \
    --ssl \
    --uri <target-connection-string>

  3. Monitor the terminal output from mongoimport. The output prints lines of text to the terminal with updates on the import operation's status.

Next step

Build a Node.js web application