Navigation

Seed with mongorestore

You can use mongodump and mongorestore to seed MongoDB Atlas cluster with data from an existing MongoDB standalone or replica set. For guidance on seeding data from an existing MongoDB sharded cluster, contact Atlas support by clicking Support in the left-hand navigation of the Atlas UI.

Considerations

Downtime Required

To ensure a completely 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 target cluster.

You must cut-over your applications to the target Atlas cluster after mongorestore completes the data restoration before resuming write operations. See Connect to a Cluster for complete documentation on connecting to a Atlas cluster.

The total amount of downtime required 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 by clicking Support from the left-hand navigation of the Atlas UI.

For a guided minimal-downtime migration procedure, see Replica Set Live Migration or Sharded Cluster Live Migration.

Cluster Security

Atlas fully manages database user creation. If the source cluster enforces authentication, use the mongorestore --nsExclude to exclude the admin.system.* namespace. You cannot migrate any existing user or role information to Atlas.

Note

If you use mongorestore with the --oplogReplay option, you will not be able to use the --nsExclude option to exclude the admin.system.* namespace. Instead, go into the dump directory created by mongodump and delete the admin directory before running mongorestore.

For the target 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. See Configure Database Users for complete documentation on database user management.

Performance

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.

Consider executing 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.

Pipe Behavior

This procedure uses linux pipes to stream the output of mongodump to mongorestore. If the mongorestore process cannot keep up with the mongodump process, you may encounter broken pipe errors.

For guidance on addressing persistent broken pipe errors, contact Atlas support by clicking Support from the left-hand navigation of the Atlas UI.

Procedure

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

1

Optional: Create a database user in the source replica set.

Optional

If your source cluster does not enforce authentication, you can 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, see MongoDB Role-Based Access Control.

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

Example

Run the following command in the mongo shell to create the mySourceUser on the admin database and assign it the backup role. For replica sets, you must run this command against the primary.

copy 
use admin
db.createUser(
  {
     user: "<mySourceUser>",
     pwd: "<mySourcePassword>",
     roles: [ "backup" ]
  }
)
2

Assemble the mongodump command.

Copy the following template to into your preferred text editor:

copy 
mongodump --host '<ReplicaSetName>/<HostList>' \
          --username '<mySourceUser>' \
          --password '<mySourcePassword>' \
          --authenticationDatabase 'admin' \
          --archive

Replace <ReplicaSetName> with the name of the source replica set. Replace <HostList> with a comma-separated list of hostnames of the replica set members. You must specify at least one member of the replica set.

For standalone deployments, exclude <ReplicaSetName>/ and specify the hostname of the standalone deployment only. For example, --host 'standalone-mongod.example.net:27017'

Add any additional command line options as required for your cluster. If your source cluster does not enforce authentication, exclude the following options:

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

3

Set up database user in the target Atlas cluster.

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. If it is not already displayed, select your desired organization from the office icon Organizations menu in the navigation bar.
  2. Click Access Manager in the sidebar, or click Access Manager in the navigation bar, then click your organization.
  3. Click plus icon Add New Database User.
  4. Add an Atlas admin user.

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

4

Navigate to the Clusters page for your project.

  1. If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
  3. If the Clusters page is not already displayed, click Clusters in the sidebar.
5

Choose Command Line Tools for your desired cluster.

From the ellipsis h icon menu for the cluster, click Command Line Tools.

6

Retrieve and modify the mongorestore connection template.

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

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

  • <atlasPassword>: 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.

Your template should resemble the following command:

mongorestore --host myAtlasCluster/00.foo.mongodb.net:27017,01.foo.mongodb.net:27017,02.foo.mongodb.net:27017 \
             --ssl \
             --username '<myAtlasUser>' \
             --password '<atlasPassword>' \
             --authenticationDatabase admin \
             --archive \
             --nsExclude 'admin.system.*'
7

Run mongodump and mongorestore.

Important

Ensure that the host where you are running mongodump and mongorestore is in the project IP whitelist.

To review your project whitelist, click Network Access in the Security section of the sidebar. The IP Whitelist tab displays. For complete documentation on managing your project whitelist, see Project IP Whitelist.

In your preferred text editor, use the pipe | operator to separate the mongodump and mongorestore commands. The final command should resemble the following:

copy 
mongodump --host 'sourceRS/source-host1:27017,source-host2:27017,source-host3:27017' \
          --archive --ssl \
          --username '<mySourceUser>' \
          --password '<sourcePassword>' \
          --authenticationDatabase admin \
| \
mongorestore --host myAtlasRS/atlas-host1:27017,atlas-host2:27017,atlas-host3:27017 \
             --archive --ssl \
             --username '<myAtlasAdminUser>' \
             --password '<atlasPassword>' \
             --authenticationDatabase admin \
             --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 your Atlas cluster using the mongo shell and verify the result of the procedure. To learn how, see Connect via mongo Shell.

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 Driver.

Additional Information

For more information on mongodump and mongorestore, including behavior, options, and examples, see the mongodump reference page and the mongorestore reference page.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.