|
| 1 | +--- |
| 2 | +title: Migrate MongoDB offline to Azure Cosmos DB for MongoDB vCore, using MongoDB native tools |
| 3 | +description: Learn how MongoDB native tools can be used to migrate small datasets from MongoDB instances to Azure Cosmos DB for MongoDB vCore |
| 4 | +author: sandnair |
| 5 | +ms.author: sidandrews |
| 6 | +ms.reviewer: mjbrown |
| 7 | +ms.service: cosmos-db |
| 8 | +ms.subservice: table |
| 9 | +ms.custom: ignite-2022 |
| 10 | +ms.topic: tutorial |
| 11 | +ms.date: 08/26/2021 |
| 12 | +--- |
| 13 | + |
| 14 | +# Migrate MongoDB to Azure Cosmos DB for MongoDB vCore offline using MongoDB native tools |
| 15 | +[!INCLUDE[MongoDB vCore](../../includes/appliesto-mongodb-vcore.md)] |
| 16 | + |
| 17 | + |
| 18 | +You can use MongoDB native tools to perform an offline (one-time) migration of databases from an on-premises or cloud instance of MongoDB to Azure Cosmos DB for MongoDB vCore. |
| 19 | + |
| 20 | +In this guide, you migrate a dataset in MongoDB hosted in an Azure Virtual Machine to Azure Cosmos DB for MongoDB vCore by using MongoDB native tools. 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, however we recommend running these tools within the same network as the MongoDB instance to avoid firewall issues. |
| 21 | + |
| 22 | +The MongoDB native tools can move data only as fast as the host hardware allows; the native tools can be the simplest solution for small datasets where total migration time isn't a concern. [MongoDB Spark connector](https://docs.mongodb.com/spark-connector/current/), or [Azure Data Factory (ADF)](../../../data-factory/connector-azure-cosmos-db-mongodb-api.md) can be better alternatives if you need a scalable migration pipeline. |
| 23 | + |
| 24 | + |
| 25 | +## Prerequisites |
| 26 | + |
| 27 | +To complete this tutorial, you need to: |
| 28 | + |
| 29 | +* [Complete the pre-migration](../pre-migration-steps.md) to create a list of incompatibilities and warnings, if any. |
| 30 | +* [Create an Azure Cosmos DB for MongoDB vCore account](./quickstart-portal.md#create-a-cluster). |
| 31 | + * [Collect the Azure Cosmos DB for MongoDB vCore credentials](./quickstart-portal.md#get-cluster-credentials) |
| 32 | + * [Configure Firewall Settings on Azure Cosmos DB for MongoDB vCore](./security.md#network-security-options) |
| 33 | +* Log in to your MongoDB instance |
| 34 | + * **Ensure that your MongoDB native tools version matches your existing MongoDB instance.** |
| 35 | + * 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.** |
| 36 | + * Add a user with `readWrite` permissions, unless one already exists. Later in this tutorial, provide this username/password to the *mongoexport* and *mongodump* tools. |
| 37 | +* [Download and install the MongoDB native tools from this link](https://www.mongodb.com/try/download/database-tools). |
| 38 | + |
| 39 | +## Choose the proper MongoDB native tool |
| 40 | + |
| 41 | + |
| 42 | + |
| 43 | +* *mongoexport/mongoimport* is the best pair of migration tools for migrating a subset of your MongoDB database. |
| 44 | + * *mongoexport* exports your existing data to a human-readable JSON or CSV file. *mongoexport* takes an argument specifying the subset of your existing data to export. |
| 45 | + * *mongoimport* opens a JSON or CSV file and inserts the content into the target database instance (Azure Cosmos DB for MongoDB vCore in this case.). |
| 46 | + * JSON and CSV aren't a compact format; you may incur excess network charges as *mongoimport* sends data to Azure Cosmos DB for MongoDB vCore. |
| 47 | +* *mongodump/mongorestore* is the best pair of migration tools for migrating your entire MongoDB database. The compact BSON format makes more efficient use of network resources as the data is inserted into Azure Cosmos DB for MongoDB vCore. |
| 48 | + * *mongodump* exports your existing data as a BSON file. |
| 49 | + * *mongorestore* imports your BSON file dump into Azure Cosmos DB for MongoDB vCore. |
| 50 | +* As an aside - 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. |
| 51 | + |
| 52 | + |
| 53 | + |
| 54 | +## Perform the migration |
| 55 | + |
| 56 | +Choose which database(s) and collection(s) you would like to migrate. In this example, we're migrating the *samples_friends* collection in the *Samples* database from MongoDB to Azure Cosmos DB for MongoDB vCore. |
| 57 | + |
| 58 | +The rest of this section guides you through using the pair of tools you selected in the previous section. |
| 59 | + |
| 60 | +### *mongoexport/mongoimport* |
| 61 | + |
| 62 | +1. To export the data from the source MongoDB instance, open a terminal on the MongoDB instance machine. If it's a Linux machine, type |
| 63 | + |
| 64 | + ```bash |
| 65 | + mongoexport --host HOST:PORT --authenticationDatabase admin -u USERNAME -p PASSWORD --db Samples --collection samples_friends --out Samples.json |
| 66 | + ``` |
| 67 | + |
| 68 | + On windows, the executable is `mongoexport.exe`. *HOST*, *PORT*, *USERNAME*, and *PASSWORD* should be filled in based on the properties of your existing MongoDB database instance. |
| 69 | + |
| 70 | + You may also choose to export only a subset of the MongoDB dataset by adding an additional filter argument: |
| 71 | + |
| 72 | + ```bash |
| 73 | + mongoexport --host HOST:PORT --authenticationDatabase admin -u USERNAME -p PASSWORD --db Samples --collection samples_friends --out Samples.json --query '{"field1":"value1"}' |
| 74 | + ``` |
| 75 | + |
| 76 | + Only documents that match the filter `{"field1":"value1"}` are exported. |
| 77 | + |
| 78 | + Once you execute the call, you should see that an `Samples.json` file is produced: |
| 79 | + |
| 80 | + |
| 81 | +1. You can use the same terminal to import `Samples.json` into Azure Cosmos DB for MongoDB vCore. If you're running `mongoimport` on a Linux machine, type |
| 82 | +
|
| 83 | + ```bash |
| 84 | + mongoimport --host HOST:PORT -u USERNAME -p PASSWORD --db Samples --collection importedQuery --ssl --type json --writeConcern="{w:0}" --file Samples.json |
| 85 | + ``` |
| 86 | +
|
| 87 | + On Windows, the executable is `mongoimport.exe`. *HOST*, *PORT*, *USERNAME*, and *PASSWORD* should be filled in based on the Azure Cosmos DB for MongoDB vCore credentials you collected earlier. |
| 88 | +1. **Monitor** the terminal output from *mongoimport*. You should see that it prints lines of text to the terminal containing updates on the import status: |
| 89 | +
|
| 90 | +
|
| 91 | +### *mongodump/mongorestore* |
| 92 | +
|
| 93 | +1. To create a BSON data dump of your MongoDB instance, open a terminal on the MongoDB instance machine. If it's a Linux machine, type |
| 94 | + |
| 95 | + ```bash |
| 96 | + mongodump --host HOST:PORT --authenticationDatabase admin -u USERNAME -p PASSWORD --db Samples --collection samples_friends --out Samples-dump |
| 97 | + ``` |
| 98 | + |
| 99 | + *HOST*, *PORT*, *USERNAME*, and *PASSWORD* should be filled in based on the properties of your existing MongoDB database instance. You should see that an `Samples-dump` directory is produced and that the directory structure of `Samples-dump` reproduces the resource hierarchy (database and collection structure) of your source MongoDB instance. Each collection is represented by a BSON file: |
| 100 | + |
| 101 | +1. You can use the same terminal to restore the contents of `Samples-dump` into Azure Cosmos DB for MongoDB vCore. If you're running `mongorestore` on a Linux machine, type |
| 102 | +
|
| 103 | + ```bash |
| 104 | + mongorestore --host HOST:PORT --authenticationDatabase admin -u USERNAME -p PASSWORD --db Samples --collection importedQuery --writeConcern="{w:0}" --ssl Samples-dump/Samples/samples_friends.bson |
| 105 | + ``` |
| 106 | +
|
| 107 | + On Windows, the executable is `mongorestore.exe`. *HOST*, *PORT*, *USERNAME*, and *PASSWORD* should be filled in based on the Azure Cosmos DB for MongoDB vCore credentials you collected earlier. |
| 108 | +1. **Monitor** the terminal output from *mongorestore*. You should see that it prints lines to the terminal updating on the migration status: |
| 109 | +
|
| 110 | +
|
| 111 | +## Next steps |
| 112 | +
|
| 113 | +- Read more about [feature compatibility with MongoDB](compatibility.md). |
| 114 | +- Get started by [creating an account](quickstart-portal.md). |
| 115 | +
|
0 commit comments