Back Up and Restore with MongoDB Tools

This tutorial describes the process for creating backups and restoring datausing the utilities provided with MongoDB.

Considerations

Deployments

The mongodump and mongorestore utilitieswork with BSON data dumps, and areuseful for creating backups of small deployments. For resilient andnon-disruptive backups, use a file system or block-level disk snapshotfunction, such as the methods described in the MongoDB Backup Methodsdocument.

Note

mongodump and mongorestorecannot be part of a backup strategy for 4.2+ sharded clustersthat have sharded transactions in progress as these tools cannotguarantee a atomicity guarantees of data across the shards.

For 4.2+ sharded clusters with in-progress sharded transactions, forcoordinated backup and restore processes that maintain the atomicityguarantees of transactions across shards, see:

Performance Considerations

Because mongodump and mongorestore operate byinteracting with a running mongod instance, they can impactthe performance of your running database. Not only do the tools createtraffic for a running database instance, they also force the database toread all data through memory. When MongoDB reads infrequently used data,it can evict more frequently accessed data, causing a deteriorationin performance for the database’s regular workload.

When backing up your data with MongoDB’s tools, consider thefollowing guidelines:

  • Label files so that you can identify the contents of thebackup as well as the point in time that the backup reflects.
  • Use an alternative backup strategy such as FilesystemSnapshots orMongoDB Cloud Manager if theperformance impact of mongodump and mongorestore is unacceptablefor your use case.
  • Use —oplog to capture incoming write operations duringthe mongodump operation to ensure that the backups reflecta consistent data state.
  • Ensure that your backups are usable by restoring them to a testMongoDB deployment.

See also

MongoDB Backup Methods and MongoDB Cloud Manager Backup documentationfor more information on backing up MongoDB instances. Additionally,consider the following reference documentation for the MongoDB import/exporttools:

Binary BSON Dumps

The mongorestore and mongodump utilities work withBSON data dumps, and are useful for creatingbackups of small deployments. For resilient and non-disruptive backups, use afile system or block-level disk snapshot function, such as the methodsdescribed in the MongoDB Backup Methods document.

Use these tools for backups if other backup methods, such asMongoDB Cloud Manager orfile system snapshotsare unavailable.

Procedures

Back Up a Database with mongodump

Note

mongodump and mongorestorecannot be part of a backup strategy for 4.2+ sharded clustersthat have sharded transactions in progress as these tools cannotguarantee a atomicity guarantees of data across the shards.

For 4.2+ sharded clusters with in-progress sharded transactions, forcoordinated backup and restore processes that maintain the atomicityguarantees of transactions across shards, see:

Exclude local Database

mongodump excludes the content of the local database in its output.

Required Access

To run mongodump against a MongoDB deployment that hasaccess control enabled, you must haveprivileges that grant find action for each database toback up. The built-in backup role provides the requiredprivileges to perform backup of any and all databases.

Changed in version 3.2.1: The backup role provides additional privileges to backup the system.profilecollection that exists when running with database profiling. Previously, users requiredread access on this collection.

Basic mongodump Operations

The mongodump utility backs up data by connecting to arunning mongod.

The utility can create a backup for an entire server, database or collection,or can use a query to backup just part of a collection.

When you run mongodump without any arguments, the commandconnects to the MongoDB instance on the local system(e.g. localhost) on port 27017 and creates adatabase backup named dump/ in the current directory.

To backup data from a mongod instancerunning on the same machine and on the default port of 27017,use the following command:

  1. mongodump

You can also specify the —host and—port of the MongoDB instance that themongodump should connect to. For example:

  1. mongodump --host=mongodb.example.net --port=27017

mongodump will write BSON files that hold a copy ofdata accessible via the mongod listening on port 27017 ofthe mongodb.example.net host. See Create Backups from Non-Local mongod Instances for moreinformation.

To specify a different output directory, you can use the —outor -o option:

  1. mongodump --out=/data/backup/

To limit the amount of data included in the database dump, you canspecify —db and—collection as options tomongodump. For example:

  1. mongodump --collection=myCollection --db=test

This operation creates a dump of the collection named myCollectionfrom the database test in a dump/ subdirectory of thecurrent working directory.

mongodump overwrites output files if they exist in thebackup data folder. Before running the mongodump commandmultiple times, either ensure that you no longer need the files in theoutput folder (the default is the dump/ folder) or rename thefolders or files.

Point in Time Operation Using Oplogs

Use the —oplog option withmongodump to collect the oplog entries to build apoint-in-time snapshot of a database within a replica set. With —oplog, mongodump copies all the data fromthe source database as well as all of the oplog entries fromthe beginning to the end of the backup procedure. This operation, inconjunction with mongorestore —oplogReplay,allows you to restore a backup that reflects the specificmoment in time that corresponds to when mongodump completedcreating the dump file.

Create Backups from Non-Local mongod Instances

The —host and—port options formongodump allow you to connect to and backup from a remote host.Consider the following example:

  1. mongodump --host=mongodb1.example.net --port=3017 --username=user --password="pass" --out=/opt/backup/mongodump-2013-10-24

On any mongodump command you may, as above, specify usernameand password credentials to specify database authentication.

Restore a Database with mongorestore

Note

mongodump and mongorestorecannot be part of a backup strategy for 4.2+ sharded clustersthat have sharded transactions in progress as these tools cannotguarantee a atomicity guarantees of data across the shards.

For 4.2+ sharded clusters with in-progress sharded transactions, forcoordinated backup and restore processes that maintain the atomicityguarantees of transactions across shards, see:

Access Control

To restore data to a MongoDB deployment that has access control enabled, the restore role providesthe necessary privileges to restore data from backups if the data doesnot include system.profilecollection data and you run mongorestore without the—oplogReplay option.

If the backup data includes system.profile collection data or you run with—oplogReplay, you needadditional privileges:

system.profileIf the backup data includes system.profile collection data and the target databasedoes not contain the system.profilecollection, mongorestore attempts to create the collectioneven though the program does not actually restore system.profiledocuments. As such, the user requires additional privileges to performcreateCollection and convertToCappedactions on the system.profilecollection for a database.Both the built-in roles dbAdmin anddbAdminAnyDatabase provide the additional privileges.
—oplogReplayTo run with —oplogReplay, create a user-defined role that has anyAction onanyResource.Grant only to users who must run mongorestorewith —oplogReplay.

Basic mongorestore Operations

The mongorestore utility restores a binary backup created bymongodump. By default, mongorestore looks for adatabase backup in the dump/ directory.

The mongorestore utility restores data by connecting to arunning mongod directly.

mongorestore can restore either an entire database backupor a subset of the backup.

Note

New in version 3.6:

All MongoDB collections haveUUIDs by default. WhenMongoDB restores collections, the restored collections retain theiroriginal UUIDs. When restoring a collection where no UUID waspresent, MongoDB generates a UUID for the restored collection.

For more information on collection UUIDs, seeCollections.

To use mongorestore to connect to an activemongod, use a command with the following prototype form:

  1. mongorestore --port=<port number> <path to the backup>

Consider the following example:

  1. mongorestore dump-2013-10-25/

Here, mongorestore imports the database backup inthe dump-2013-10-25 directory to the mongod instancerunning on the localhost interface on the default port 27017.

Restore Point in Time Oplog Backup

If you created your database dump using the —oplog option to ensure a point-in-time snapshot, callmongorestore with the—oplogReplayoption, as in the following example:

  1. mongorestore --oplogReplay

You may also consider using the mongorestore —objcheckoption to check the integrity of objects while inserting them into thedatabase, or you may consider the mongorestore —drop option to drop eachcollection from the database before restoring frombackups.

Restore Backups to Non-Local mongod Instances

By default, mongorestore connects to a MongoDB instancerunning on the localhost interface and on thedefault port (27017). If you want to restore to a different host orport, use the —host and —port options.

The following example that specifies the —host and —port options:

  1. mongorestore --host=mongodb1.example.net --port=3017

If restoring to an instance that enforces access control, include thethe —username and—authenticationDatabase as well. Omit the —password option to have mongorestoreprompt for the password:

  1. mongorestore --host=mongodb1.example.net --port=3017 --username=user  --authenticationDatabase=admin /opt/backup/mongodump-2013-10-24