- Administration >
- Administration Tutorials >
- Backup and Recovery >
- Back Up and Restore with MongoDB Tools
Back Up and Restore with MongoDB Tools¶
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.
See also
MongoDB Backup Methods or MongoDB Cloud Manager Backup documentation for more information on backing up MongoDB instances. Additionally, consider the following references for the MongoDB import/export tools:
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
¶
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.0.9: 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:
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
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:
To limit the amount of data included in the database dump, you can
specify --db
and
--collection
as options to
mongodump
. For example:
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:
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
,
create a 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:
Consider the following example:
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:
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:
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.
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
:
Then, using the --fieldFile
option, specify the fields to export with
the file:
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.
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
.
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
.
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.
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
.
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
uses the input file name, without the
extension, as the collection name if -c
or --collection
is
unspecified. The following example is therefore equivalent:
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.