Load Data into an Atlas Infinite Cluster

Set up a database user in the source deployment.

If the source deployment enforces authentication, mongodump must authenticate as a database user that can read every database you migrate. The backup role on the admin database grants these privileges.

If no such user exists in your source deployment, create one. To learn how to create and manage database users, see the following page for your deployment type:

• For Atlas-managed clusters, see Configure Database Users.

• For self-managed deployments, see Manage Users and Roles on Self-Managed Deployments.

Set up a database user in the destination Atlas Infinite cluster.

mongorestore must authenticate as a database user that can write to every database you migrate. The Atlas admin role on the destination Atlas Infinite cluster grants these privileges.

If no such user exists in your destination Atlas Infinite cluster, create one. To learn how to create and manage database users in Atlas, see Configure Database Users.

Grant your host network access to the source and destination deployments.

Ensure that the host where you run mongodump and mongorestore can reach both deployments:

• Add the host to the IP access list for the project that contains your destination Atlas Infinite cluster. To learn how to add a host to an IP access list, see Configure IP Access List Entries.

• If your source deployment is an Atlas Core cluster in a different project, add the host to that project's IP access list as well. If your source deployment is self-managed, configure its firewall to accept connections from the host. To learn more, see Network and Configuration Hardening.

If you set up VPC peering, you can add the peer's VPC CIDR block or a subnet, or the peer VPC's security group to the IP access list. To learn more, see IP Access List.

Run mongodump.

1. Assemble the mongodump command.

   The following mongodump command template connects to a source replica set or standalone cluster using its connection string, and outputs an archive of the dump to a file.

   Copy the template into your preferred text editor and replace the <connectionString> placeholder with the connection string for your source deployment, and <fileName> with the name of the archive file to create.

   mongodump --uri "<connectionString>" --archive=<fileName>.archive

   To learn how to construct a connection string for your source deployment, see Connection Strings.

   Note

   If using mongodump or mongorestore on Ubuntu 18.04, you may experience a cannot unmarshal DNS error message when using SRV connection strings (in the form mongodb+srv://) with the --uri option. If so, use one of the following options instead:

   • the --uri option with a non-SRV connection string (in the form mongodb://)

   • the --host option to specify the host to connect to directly

2. Run the completed command from a terminal or command prompt on a host that has network access to your source deployment.

   Example

   The following mongodump command connects to a source Atlas Core cluster using an SRV connection string, which contains the username (mySourceUsername) and password (mySourcePassword) for a database user with the backup role on the admin database. The command outputs an archive of the dump to a file named mongodump.archive in the current working directory.

   mongodump --uri "mongodb+srv://mySourceUsername:mySourcePassword@cluster0.example.mongodb.net" \
             --archive="mongodump.archive"

Run mongorestore.

1. Assemble the mongorestore command.

   The following mongorestore command template connects to your destination Atlas Infinite cluster using its connection string and restores the archive created by mongodump. It uses --nsExclude to exclude the admin and config databases, which Atlas manages.

   Copy the template into your preferred text editor and replace the following placeholders with the appropriate values:

   • <connectionString>: replace this with the SRV connection string for your destination Atlas Infinite cluster. To retrieve or construct a connection string for your destination cluster, see Connection Strings.

     Include the username and password for a database user with the Atlas admin role in the connection string.

   • <filePath>: replace this with the path to the archive file created by mongodump.

   Note

   If the username or password includes the following characters, those characters must be converted using percent encoding:

   $ : / ? # [ ] @

   mongorestore --uri "<connectionString>" \
                --archive="<filePath>" \
                --nsExclude "admin.*" \
                --nsExclude "config.*"

2. Run the completed command from a terminal or command prompt on a host that has access to the archive file created by mongodump.

   Example

   The following mongorestore command connects to an Atlas Infinite cluster using an SRV connection string, which contains the username (myDestinationUsername) and password (myDestinationPassword) for a database user with the Atlas admin role. The command restores the archive at mongodump.archive created by mongodump, excluding the admin and config databases.

   mongorestore --uri "mongodb+srv://myDestinationUsername:myDestinationPassword@cluster0.example.mongodb.net" \
             --archive="mongodump.archive" \
             --nsExclude "admin.*" \
             --nsExclude "config.*"

Verify the migration.

After the migration is complete, connect to your Atlas Infinite cluster and verify that the data has been migrated successfully. You can run queries to check the presence of your collections and documents in the destination cluster.

Update your applications to point to the Atlas Infinite cluster.

After verifying the migration, update your applications to connect to the Atlas Infinite cluster instead of the source deployment. Ensure that you use the correct connection string and credentials for the Atlas Infinite cluster.

In Atlas, go to the Database & Network Access page for your project.

1. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.

2. If it's not already displayed, select your project from the Projects menu in the navigation bar.

3. In the sidebar, click Database & Network Access under the Security heading.

The Database & Network Access page displays after you complete the preceding steps.

Set up a database user in the destination Atlas cluster.

To run mongoimport to write to an Atlas cluster, you must specify a database user that has readWrite privileges in the database into which to import data. For example, a user with Atlas admin role provides these privileges.

If no such user exists, create the user:

1. If it isn't already displayed, click the Database Users tab.

2. Click Add New Database User.

3. Add an Atlas admin user.

In Atlas, go to the Clusters page for your project.

1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

3. In the sidebar, click Clusters under the Database heading.

The Clusters page displays.

Click Connect.

Click Connect for the Atlas cluster into which you want to migrate data.

Update IP Access List.

If the host where you will run mongoimport is not in the IP Access List, update the list. You can specify either:

• The public IP address of the server on which mongoimport will run, or

• If set up for VPC peering, either the peer's VPC CIDR block (or a subnet) or the peer VPC's Security Group, if you chose AWS as your cloud provider.

Copy the destination cluster URI / host information.

You can connect to your Atlas cluster using its connection string URI. In the connect dialog box perform the following steps:

1. Click Drivers.

2. Copy the connection string found in step 1.

3. Replace PASSWORD with the password for the root user, and DATABASE with the name of the database to which you wish to connect.

   Important

   You must escape any instances of the @ character in the provided <PASSWORD>. For example, p@ssword should be p%40ssword.

This connection string is specified to mongoimport in the --uri option.

When using --host, if the Atlas cluster is a replica set you must also retrieve the replica set name. For example:

myAtlasRS/atlas-host1:27017,atlas-host2:27017,atlas-host3:27017

Run mongoimport.

Connect to your Atlas Infinite cluster.

To run the bulk write operations in this procedure, connect to your cluster with mongosh. To learn how, see Connect to an Atlas Cluster.

You can also run bulk write operations from application code with a MongoDB driver, from the Atlas UI, or from any other interface that connects to your cluster. To learn about the equivalent operations in each interface, see Bulk Write Operations.

Run the bulk write operation.

To write to a single collection, run bulkWrite(). To learn more about write operation types and bulk write options, see bulkWrite().

For example, the following command inserts two documents into the inventory collection:

db.inventory.bulkWrite( [
   { insertOne: { document: {
      _id: ObjectId("68b1c2d3e4f5a6b7c8d9e0f1"),
      item: "notebook",
      qty: 50
   } } },
   { insertOne: { document: {
      _id: ObjectId("68b1c2d3e4f5a6b7c8d9e0f2"),
      item: "pencil",
      qty: 100
   } } }
] )

To write to multiple collections or databases in one request, run bulkWrite() and specify the namespace for each operation. For example, the following command inserts one document into the sales.inventory collection and one document into the supplies.inventory collection:

db.getMongo().bulkWrite( [
   {
      namespace: "sales.inventory",
      name: "insertOne",
      document: { item: "notebook", qty: 50 }
   },
   {
      namespace: "supplies.inventory",
      name: "insertOne",
      document: { item: "pencil", qty: 100 }
   }
] )

By default, bulk write operations run in order and stop at the first error. To learn how to configure run order, see Execution of Operations.

Verify the results.

Review the counts that the operation returns and confirm the document count in each target collection. To learn more, see Output.

To learn how to handle errors for bulk write operations, see Error Handling.