Back Up and Restore with MongoDB Tools¶

On this page

Binary BSON Dumps
Human Intelligible Import/Export Formats

This document describes the process for creating backups and restoring data using the utilities provided with MongoDB.

Because all of these tools primarily operate by interacting with a running mongod instance, they can impact the performance of your running database.

Not only do they create traffic for a running database instance, they also force the database to read all data through memory. When MongoDB reads infrequently used data, it can supplant more frequently accessed data, causing a deterioration in performance for the database’s regular workload.

No matter how you decide to import or export your data, consider the following guidelines:

Label files so that you can identify the contents of the export or backup as well as the point in time the export/backup reflect.
Do not create or apply exports if the backup process itself will have an adverse effect on a production system.
Make sure that the backups reflect a consistent data state. Export or backup processes can impact data integrity (i.e. type fidelity) and consistency if updates continue during the backup process.
Test backups and exports by restoring and importing to ensure that the backups are useful.

Binary BSON Dumps¶

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 a file system or block-level disk snapshot function, such as the methods described in the MongoDB Backup Methods document.

Use these tools for backups if other backup methods, such as the MongoDB Cloud Manager or file system snapshots are unavailable.

Backup a Database with `mongodump`¶

Exclude `local` Database¶

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

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.

Changed in version 3.2.1: The backup role provides additional privileges to back up the system.profile collections that exist when running with database profiling. Previously, users required an additional read access on this collection.

Basic `mongodump` Operations¶

The mongodump utility backs up data by connecting to a running mongod or mongos instance.

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 command connects to the MongoDB instance on the local system (e.g. 127.0.0.1 or localhost) on port 27017 and creates a database backup named dump/ in the current directory.

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

mongodump

The data format used by mongodump from version 2.2 or later is incompatible with earlier versions of mongod. Do not use recent versions of mongodump to back up older data stores.

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

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

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

To specify a different output directory, you can use the --out or -o option:

mongodump --out /data/backup/

To limit the amount of data included in the database dump, you can specify --db and --collection as options to mongodump. For example:

mongodump --collection myCollection --db test

This operation creates a dump of the collection named myCollection from the database test in a dump/ subdirectory of the current working directory.

mongodump overwrites output files if they exist in the backup data folder. Before running the mongodump command multiple times, either ensure that you no longer need the files in the output folder (the default is the dump/ folder) or rename the folders or files.

Point in Time Operation Using Oplogs¶

Use the --oplog option with mongodump to collect the oplog entries to build a point-in-time snapshot of a database within a replica set. With --oplog, mongodump copies all the data from the source database as well as all of the oplog entries from the beginning to the end of the backup procedure. This operation, in conjunction with mongorestore --oplogReplay, allows you to restore a backup that reflects the specific moment in time that corresponds to when mongodump completed creating the dump file.

Create Backups from Non-Local `mongod` Instances¶

The --host and --port options for mongodump allow you to connect to and backup from a remote host. Consider the following example:

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 username and password credentials to specify database authentication.

Restore a Database with `mongorestore`¶

Access Control¶

To restore data to a MongoDB deployment that has access control enabled, the restore role provides access to restore any database if the backup data does not include system.profile collection data.

If the backup data includes system.profile collection data and the target database does not contain the system.profile collection, mongorestore attempts to create the collection even though the program does not actually restore system.profile documents. As such, the user requires additional privileges to perform createCollection and convertToCapped actions on the system.profile collection for a database.

If running mongorestore with --oplogReplay, additional privilege user-defined role that has anyAction on anyResource and grant only to users who must run mongorestore with --oplogReplay.

Basic `mongorestore` Operations¶

The mongorestore utility restores a binary backup created by mongodump. By default, mongorestore looks for a database backup in the dump/ directory.

The mongorestore utility restores data by connecting to a running mongod or mongos directly.

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

To use mongorestore to connect to an active mongod or mongos, use a command with the following prototype form:

mongorestore --port <port number> <path to the backup>

Consider the following example:

mongorestore dump-2013-10-25/

Here, mongorestore imports the database backup in the dump-2013-10-25 directory to the mongod instance running on the localhost interface.

Restore Point in Time Oplog Backup¶

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

mongorestore --oplogReplay

You may also consider using the mongorestore --objcheck option to check the integrity of objects while inserting them into the database, or you may consider the mongorestore --drop option to drop each collection from the database before restoring from backups.

Restore Backups to Non-Local `mongod` Instances¶

By default, mongorestore connects to a MongoDB instance running on the localhost interface (e.g. 127.0.0.1) and on the default port (27017). If you want to restore to a different host or port, use the --host and --port options.

Consider the following example:

mongorestore --host mongodb1.example.net --port 3017 --username user --password pass /opt/backup/mongodump-2013-10-24

As above, you may specify username and password connections if your mongod requires authentication.

Human Intelligible Import/Export Formats¶

MongoDB’s mongoimport and mongoexport tools allow you to work with your data in a human-readable Extended JSON or CSV format. This is useful for simple ingestion to or from a third-party system, and when you want to backup or export a small subset of your data. For more complex data migration tasks, you may want to write your own import and export scripts using a client driver to interact with the database.

The examples in this section use the MongoDB tools mongoimport and mongoexport. These tools may also be useful for importing data into a MongoDB database from third party applications.

If you want to simply copy a database or collection from one instance to another, consider using the copydb, clone, or cloneCollection commands, which may be more suited to this task. The mongo shell provides the db.copyDatabase() method.

Warning

Avoid using mongoimport and mongoexport for full instance production backups. They do not reliably preserve all rich BSON data types, because JSON can only represent a subset of the types supported by BSON. Use mongodump and mongorestore as described in MongoDB Backup Methods for this kind of functionality.

Collection Export with `mongoexport`¶

Export in CSV Format¶

Changed in version 3.0.0: mongoexport removed the --csv option. Use the --type=csv option to specify CSV format for the output.

In the following example, mongoexport exports data from the collection contacts collection in the users database in CSV format to the file /opt/backups/contacts.csv.

The mongod instance that mongoexport connects to is running on the localhost port number 27017.

When you export in CSV format, you must specify the fields in the documents to export. The operation specifies the name and address fields to export.

mongoexport --db users --collection contacts --type=csv --fields name,address --out /opt/backups/contacts.csv

For CSV exports only, you can also specify the fields in a file containing the line-separated list of fields to export. The file must have only one field per line.

For example, you can specify the name and address fields in a file fields.txt:

name
address

Then, using the --fieldFile option, specify the fields to export with the file:

mongoexport --db users --collection contacts --type=csv --fieldFile fields.txt --out /opt/backups/contacts.csv

Changed in version 3.0.0: mongoexport removed the --csv option and replaced with the --type option.

Export in JSON Format¶

This example creates an export of the contacts collection from the MongoDB instance running on the localhost port number 27017. This writes the export to the contacts.json file in JSON format.

mongoexport --db sales --collection contacts --out contacts.json

Export from Remote Host Running with Authentication¶

The following example exports the contacts collection from the marketing database, which requires authentication.

This data resides on the MongoDB instance located on the host mongodb1.example.net running on port 37017, which requires the username user and the password pass.

mongoexport --host mongodb1.example.net --port 37017 --username user --password pass --collection contacts --db marketing --out mdb1-examplenet.json

Export Query Results¶

You can export only the results of a query by supplying a query filter with the --query option, and limit the results to a single database using the “--db” option.

For instance, this command returns all documents in the sales database’s contacts collection that contain a field named field with a value of 1.

mongoexport --db sales --collection contacts --query '{"field": 1}'

You must enclose the query in single quotes (e.g. ') to ensure that it does not interact with your shell environment.

Collection Import with `mongoimport`¶

Simple Usage¶

mongoimport restores a database from a backup taken with mongoexport. Most of the arguments to mongoexport also exist for mongoimport.

In the following example, mongoimport imports the data in the JSON data from the contacts.json file into the collection contacts in the users database.

mongoimport --db users --collection contacts --file contacts.json

Import `JSON` to Remote Host Running with Authentication¶

In the following example, mongoimport imports data from the file /opt/backups/mdb1-examplenet.json into the contacts collection within the database marketing on a remote MongoDB database with authentication enabled.

mongoimport connects to the mongod instance running on the host mongodb1.example.net over port 37017. It authenticates with the username user and the password pass.

mongoimport --host mongodb1.example.net --port 37017 --username user --password pass --collection contacts --db marketing --file /opt/backups/mdb1-examplenet.json

`CSV` Import¶

In the following example, mongoimport imports the csv formatted data in the /opt/backups/contacts.csv file into the collection contacts in the users database on the MongoDB instance running on the localhost port numbered 27017.

Specifying --headerline instructs mongoimport to determine the name of the fields using the first line in the CSV file.

mongoimport --db users --collection contacts --type csv --headerline --file /opt/backups/contacts.csv

mongoimport uses the input file name, without the extension, as the collection name if -c or --collection is unspecified. The following example is therefore equivalent:

mongoimport --db users --type csv --headerline --file /opt/backups/contacts.csv

Use the “--ignoreBlanks” option to ignore blank fields. For CSV and TSV imports, this option provides the desired functionality in most cases because it avoids inserting fields with null values into your collection.

Additional Resources¶

← Restore a Replica Set from MongoDB Backups Backup and Restore Sharded Clusters →

Was this page helpful?

Yes No

Thank you for your feedback!

We're sorry! You can Report a Problem to help us improve this page.

Back Up and Restore with MongoDB Tools¶

Binary BSON Dumps¶

Backup a Database with mongodump¶

Exclude local Database¶