Seed with mongorestore (original) (raw)

You can use mongodump and mongorestore to seed MongoDB Atlascluster with data from an existing MongoDB standalone or replica set. For guidance on seeding data from an existing MongoDB sharded cluster, contact Atlas support:

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

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. Next to the Projects menu, expand the Options menu, then clickProject Support.
   The Project Support page displays.

While you can scale an M0 Free Tier cluster to an M10+ paid cluster using the Atlas UI, you can also usemongodump and mongorestore procedures in this section to copy data from an M0 Free Tier cluster to an M10+ cluster.

Use the latest stable release version of mongodump and mongorestorefor this procedure.

To ensure an up-to-date migration, schedule a maintenance window where you can stop all writes to your source cluster. Any write operations issued to the source cluster after the mongodump portion of the procedure completes are not migrated to the destination cluster.

After mongorestore completes data restoration, you must cut-over your applications to the destination Atlas cluster before resuming write operations. To connect to an Atlas cluster, seeConnect to a Cluster.

The total amount of required downtime depends on factors such as the size of data being migrated and the network connection between your source cluster and Atlas. If you have questions or concerns about extended downtime, contact Atlas support:

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

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. Next to the Projects menu, expand the Options menu, then clickProject Support.
   The Project Support page displays.

For a guided minimal-downtime migration procedure for MongoDB versions before 6.0, seeReplica Set Live Migration.

Atlas manages database user creation. If the source cluster enforces authentication:

• Allow read access to the primary.
• If you want to use mongorestore with the--oplogReplay option, you must delete the admin and config directories from the dump directory thatmongodump creates. The admin and configdirectories contain database user information that you can't add toan Atlas cluster with mongorestore. Use the mongorestore --nsExclude to exclude theadmin.system.* namespace.

You can't migrate any existing user or role information to Atlas. For the destination Atlas cluster, create the appropriate database users for supporting your application's usage patterns. Update your applications as part of the cut-over procedure to use the new database users. To learn more, see Configure Database Users.

This procedure requires running mongodump and mongorestore on a host in the source cluster. These programs use system resources such as CPU and memory, and may impact the performance of the host.

Run this procedure during non-peak system usage, or during a scheduled maintenance window. If the source is a replica set, you can run this procedure from the host of a secondary member. After stopping writes to the cluster, allow the secondary to catch up to the primary before starting this procedure.

This procedure useslinux pipes to stream the output of mongodump to mongorestore. If the mongorestore process can't keep up with the mongodump process, you may see broken pipe errors.

For guidance on addressing persistent broken pipe errors, contact Atlassupport:

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

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. Next to the Projects menu, expand the Options menu, then clickProject Support.
   The Project Support page displays.

The following tutorial uses mongodump and mongorestore to upload data from an existing MongoDB cluster to an Atlas cluster:

Important

Optional

If your source cluster doesn't enforce authentication, skip this step.

If the source deployment enforces authentication, you must provide a database user with privileges to read any database as part of this procedure. To learn more about database user privileges, seeMongoDB Role-Based Access Control.

If no such user exists, create a user in your source MongoDB replica set with the backuprole on the admin database.

Example

Run the following command in mongosh to create themySourceUser on the admin database and assign it thebackup role. For replica sets, you must run this command against the primary.

use admin

db.createUser(

  {

     user: "<mySourceUser>",

     pwd: "<mySourcePassword>",

     roles: [ "backup" ]

  }

)

Based on the type of connection string you use, copy one of the following templates to into your preferred text editor:

Note

To connect to Atlas clusters, we recommend you connect with a DNS seed list connection string using the --uri option.

mongodump --uri "mongodb://username:password@mongodb0.example.com:<Port>,mongodb1.example.com:<Port1>,mongodb2.example.com:<Port2>/?replicaSet=<ReplicaSetName>&authSource=admin" \

          --archive

Replace the host examples with the information for your replica set members. Replace <ReplicaSetName> with the name of the source replica set.

For standalone deployments, exclude replicaSet=<ReplicaSetName> and specify the hostname of the standalone deployment only. For example, --uri "mongodb://standalone-mongod.example.net:27017"

mongodump --uri "mongodb+srv://username:password@cluster0.example.mongodb.net" \

          --archive

Note

If using mongodump or mongorestore on Ubuntu 18.04, you may experience a cannot unmarshal DNS error message when usingSRV 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 formmongodb://)
• the --host option to specify the host to connect to directly

Note

If your password contains special characters, it must be percent-encoded.

Do not run this command yet. Proceed to the next step once you have modified the template.

To run mongorestore against an Atlas cluster, you must specify a database user in the Atlas cluster that has the Atlas admin role.

If no such user exists, create the user:

1. In Atlas, go to the Organization Access Manager page.

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
2. Do one of the following steps:
   • Select Organization Access from theAccess Manager menu in the navigation bar.
   • Click Access Manager in the sidebar.
     The Organization Access Manager page displays.
3. Click Add New Database User.
4. Add an Atlas admin user.

To learn more about user management, see Configure Database Users.

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

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. If it's not already displayed, click Clusters in the sidebar.
   The Clusters page displays.

From the menu for the cluster, clickCommand Line Tools.

The Binary Import and Export Tools section of theCommand Line Tools tab displays a copyable template with the minimum required options for connecting mongorestore to yourAtlas cluster.

The template includes placeholder values for certain options. Copy and paste the template into your preferred text editor and make the following modifications:

• password: replace this with the password for the user specified in username. The template includes a database user for the project as the username. If you want to authenticate as a different user, replace the value of username and specify the password for that user in password.
• Add --nsExclude and set its value to "admin.system.*".
• Add --archive.

Based on the type of connection string you use, your template should resemble one of the following commands:

mongorestore --uri "mongodb://username:password@00.foo.mongodb.net:27017,01.foo.mongodb.net:27017,02.foo.mongodb.net:27017/?replicaSet=myRepl&authSource=admin" \

             --archive \

             --ssl \

             --nsExclude "admin.system.*"

mongorestore --uri "mongodb+srv://username:password@cluster1.example.mongodb.net" \

             --archive \

             --nsExclude "admin.system.*"

Important

Ensure that the host where you are running mongodump andmongorestore is in the project IP Access List.

To review your project IP access list, click Network Access in the Security section of the sidebar. TheIP Access List tab displays. To learn more, see IP Access List.

In your preferred text editor, use the pipe | operator to separate the mongodump and mongorestore commands. Based on the type of connection string you use, the final command should resemble one of the following:

mongodump --uri "mongodb://username:password@mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?replicaSet=sourceRS&authSource=admin" \

          --archive \

| \

mongorestore --uri "mongodb://username:password@00.foo.mongodb.net:27017,01.foo.mongodb.net:27017,02.foo.mongodb.net:27017/?replicaSet=myAtlasRS&authSource=admin" \

             --archive \

             --ssl \

             --nsExclude "admin.system.*"

mongodump --uri "mongodb+srv://username:password@cluster0.example.mongodb.net" \

          --archive \

| \

mongorestore --uri "mongodb+srv://username:password@cluster1.example.mongodb.net" \

             --archive \

             --nsExclude "admin.system.*"

Run the completed command from a terminal or shell connected to a host machine on your source cluster.

Upon successful completion of the procedure, connect to yourAtlas cluster using mongosh and verify the result of the procedure. To learn how, see Connect via mongosh.

You must update your applications to point to the Atlas cluster before resuming write operations. To learn how to connect applications to Atlas, see Connect via Drivers.

See also:

• mongodump reference page
• mongorestore reference page