This tutorial covers creating backups and restoring data using mongodump and mongorestore.
To restore a backup of your self-hosted deployment to a managed MongoDB Atlas deployment, see Seed with mongorestore.
Considerations
Deployments
The mongorestore and mongodump utilities work with BSON data dumps, and are useful for creating backups of small deployments. For resilient and non-disruptive backups, use file system snapshots or block-level disk snapshots with Cloud Backups from MongoDB Atlas.
Note
Back Up Sharded Clusters with MongoDB Atlas
To use mongodump and mongorestore as a backup strategy for sharded clusters, see Back Up a Self-Managed Sharded Cluster with a Database Dump.
Sharded clusters can also use one of the following coordinated backup and restore processes, which maintain the atomicity guarantees of transactions across shards:
Performance Impacts
Because mongodump and mongorestore interact with a running mongod instance, they can impact database performance. The tools create traffic and force the database to read all data through memory. When MongoDB reads infrequently accessed data, it evicts frequently accessed data, degrading performance for the database's regular workload.
When backing up data with MongoDB tools, follow these guidelines:
Label files to identify backup contents and the backup time.
If the performance impact of
mongodumpandmongorestoreis unacceptable, use an alternative such as Filesystem Snapshots or Cloud Backups in MongoDB Atlas.To ensure
mongodumpcan take a consistent backup of a replica set, you must either use the--oplogoption to capture writes received during backup operations or stop all writes to the replica set for the duration of the backup.For sharded cluster replica sets, see Back Up a Self-Managed Sharded Cluster with a Database Dump.
Verify your backups by restoring them to a test deployment.
To reduce backup inconsistencies in a sharded cluster, stop the balancer, all write operations, and any schema transformations during the backup.
Tip
For more information, see Backup Methods for a Self-Managed Deployment. For MongoDB Database Tools reference, see:
Output Format
mongorestore and mongodump can output data to an archive file, which is a single-file alternative to multiple BSON files. Archive files are special-purpose formats that support non-contiguous file writes. They enable concurrent backups from MongoDB and restores to MongoDB. Archive files also optimize disk I/O during backup and restore.
You can also write archive files to standard output (stdout). Writing to standard output enables data migration over networks, reduced disk I/O, and concurrency gains in both MongoDB tools and your storage engine.
For more information on archive files, see the --archive option.
Stale Backups
Backups provide a snapshot of the current state of the database. When you restore from a backup, the restored database doesn't include any changes made after the backup was taken, which can result in data loss.
Procedures
Back Up a Database with mongodump
The mongodump utility backs up data by connecting to a running mongod. It can back up an entire server, database, or collection, or use a query to back up part of a collection. mongodump excludes the content of the local database from its output.
Without any arguments, mongodump connects to the MongoDB instance on the local system on port 27017 and creates a database backup named dump/ in the current directory:
mongodump
To specify the host and port, use one of the following:
Specify the hostname and port in
--host:mongodump --host="mongodb0.example.com:27017" <additional_options> Specify
--hostand--portseparately:mongodump --host="mongodb0.example.com" --port=27017 <additional_options>
To specify a different output directory, use --out (or -o):
mongodump --out=/opt/backup/mongodump-1
To limit the dump to a specific database or collection, use --db and --collection:
mongodump --collection=myCollection --db=test
This creates a dump of myCollection from the test database in a dump/ subdirectory of the current directory.
mongodump overwrites existing files in the output folder (default: dump/). Before running it multiple times, back up or rename the output folder.
Required Access
To run mongodump against a MongoDB deployment that has access control enabled, you must have privileges that grant find action for each database to back up. The built-in backup role provides the required privileges to perform backup of any and all databases.
The backup role provides additional privileges to back up the system.profile collection that exists when running with database profiling.
Specify Host and Port
Use --host and --port to connect to a remote instance:
mongodump \ --host=mongodb1.example.net \ --port=3017 \ --username=user \ --password="pass" \ --out=/opt/backup/mongodump-1
Specify username and password on any mongodump command to authenticate.
Create Backups Using Oplogs
The --oplog option collects oplog entries during the backup so you can restore the database to its state at the moment the backup completed.
With --oplog, mongodump copies all data from the source database and all oplog entries from the beginning to the end of the backup. Use this in conjunction with mongorestore --oplogReplay to restore a backup that reflects the exact moment mongodump completed.
Restore a Database with mongorestore
The mongorestore utility restores a binary backup created by mongodump by connecting to a running mongod directly. By default, mongorestore looks for a database backup in the dump/ directory and can restore an entire backup or a subset.
Note
All MongoDB collections have UUIDs by default. When MongoDB restores collections, the restored collections retain their original UUIDs. When restoring a collection where no UUID was present, MongoDB generates a UUID for the restored collection.
For more information on collection UUIDs, see Collections.
To connect mongorestore to an active mongod:
mongorestore --uri <connection string> <path to the backup>
For example, to restore from a directory:
mongorestore /opt/backup/mongodump-1
This restores the backup to the mongod instance on localhost:27017.
Access Control
To restore data to a deployment that has access control enabled, the restore role provides the necessary privileges if the data does not include system.profile collection data and you run mongorestore without the --oplogReplay option.
You need additional privileges if the backup data includes system.profile collection data or you run with --oplogReplay:
| If the backup data includes Both the built-in roles |
| To run with Grant only to users who must run |
Specify Host and Port
By default, mongorestore connects to localhost:27017. To restore to a different host or port, use --host and --port:
mongorestore --host=mongodb1.example.net --port=3017
To authenticate, include --username and --authenticationDatabase. Omit --password to have mongorestore prompt for the password:
mongorestore \ --host=mongodb1.example.net \ --port=3017 \ --username=user \ --authenticationDatabase=admin \ /opt/backup/mongodump-1
Use an Oplog File to Restore Data
To capture writes that occur while mongodump is running, use --oplog. mongodump creates an oplog.bson file with oplog entries for each write during the run. Apply those operations with --oplogReplay when restoring.
For examples, see mongodump Examples and mongorestore Examples.
mongorestore --oplogReplay restores all data from oplog.bson but does not support restoring to an arbitrary point in time. Use it to ensure the restored data reflects any writes that occurred during the mongodump --oplog run.
Note
--oplog is intended for use with replica sets. For sharded clusters, including replica sets that are part of a sharded environment, see Back Up a Self-Managed Sharded Cluster with a Database Dump.
Use --objcheck to validate document integrity during insertion, or --drop to drop each collection before restoring.