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¶
Minimum Recommended mongodump
and mongorestore
Version¶
Use the 3.6.0 or greater version of mongodump
and mongorestore
for this procedure.
If possible, use the latest stable release of both programs.
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.
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:
Optional: Create a database user in the source replica set.¶
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, 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.
Assemble the mongodump
command.¶
Based on the type of connection string you use, copy one of the following templates to into your preferred text editor:
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"
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.
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:
- If it is not already displayed, select your desired organization from the Organizations menu in the navigation bar.
- Click Access Manager in the sidebar, or click Access Manager in the navigation bar, then click your organization.
- Click Add New Database User.
- Add an Atlas admin user.
To learn more about user management, see Configure Database Users.
Navigate to the Clusters page for your project.¶
- If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
- If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
- If the Clusters page is not already displayed, click Clusters in the sidebar.
Choose Command Line Tools for your desired cluster.¶
From the menu for the cluster, click Command Line Tools.
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:
password
: replace this with the password for the user specified inusername
. The template includes a database user for the project as theusername
. If you want to authenticate as a different user, replace the value ofusername
and specify the password for that user inpassword
.- 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.*"
Run mongodump
and mongorestore
.¶
Ensure that the host where you are running mongodump
and
mongorestore
is in the project IP Access List.
To review your project IP access list, click Network Access in the Security section of the sidebar. The IP Access List tab displays.
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.*"
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
.