- 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 writing and restoring backups
to files in binary format with the mongodump
and
mongorestore
tools.
Use these tools for backups if other backup methods, such as the MongoDB Cloud Manager or file system snapshots are unavailable.
See also
Backup a Database with mongodump
¶
mongodump
does not dump the content of the local
database.
To backup all the databases in a cluster via mongodump
, you
should have the backup
role. The backup
role provides
all the needed privileges for backing up all database. The role confers no
additional access, in keeping with the policy of least privilege.
To backup a given database, you must have read
access on the database.
Several roles provide this access, including the backup
role.
To backup the system.profile
collection in a database, you must have
read
access on certain system collections in the database. Several roles
provide this access, including the clusterAdmin
and
dbAdmin
roles.
Changed in version 2.6.
To backup users and user-defined roles for a
given database, you must have access to the admin
database. MongoDB
stores the user data and role definitions for all databases in the
admin
database.
Specifically, to backup a given database’s users, you must have the
find
action on the admin
database’s admin.system.users
collection. The backup
and userAdminAnyDatabase
roles both provide this privilege.
To backup the user-defined roles on a database, you must have the
find
action on the admin
database’s
admin.system.roles
collection. Both the backup
and
userAdminAnyDatabase
roles provide this privilege.
Basic mongodump
Operations¶
The mongodump
utility can back up data by either:
- connecting to a running
mongod
ormongos
instance, or - accessing data files without an active 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 use mongodump
without a running MongoDB instance, specify
the --dbpath
option to read directly
from MongoDB data files. See Create Backups Without a Running mongod Instance for details.
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 Without a Running mongod
Instance¶
If your MongoDB instance is not running, you can use the
--dbpath
option to specify the
location to your MongoDB instance’s database files. mongodump
reads from the data files directly with this operation. This
locks the data directory to prevent conflicting writes. The
mongod
process must not be running or attached to these
data files when you run mongodump
in this
configuration. Consider the following example:
Given a MongoDB instance that contains the customers
,
products
, and suppliers
databases, the following
mongodump
operation backs up the databases using the
--dbpath
option, which specifies the
location of the database files on the host:
The --out or -o
option allows you to
specify the directory where mongodump
will save the backup.
mongodump
creates a separate backup directory for each of
the backed up databases: dataout/customers
,
dataout/products
, and dataout/suppliers
.
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
¶
Changed in version 2.6.
To restore users and user-defined roles on a
given database, you must have access to the admin
database. MongoDB
stores the user data and role definitions for all databases in the
admin
database.
Specifically, to restore users to a given database, you must have the
insert
action on the admin
database’s admin.system.users
collection. The restore
role provides this privilege.
To restore user-defined roles to a database, you must have the
insert
action on the admin
database’s
admin.system.roles
collection. The restore
role
provides this privilege.
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 can restore data either by:
- connecting to a running
mongod
ormongos
directly, or - writing to a set of MongoDB data files without use of a running
mongod
.
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:
To use mongorestore
to write to data files
without using a running mongod
, 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 a Subset of data from a Binary Database Dump¶
mongorestore
also includes the ability to a filter
to all input before inserting it into the new database. Consider the
following example:
Here, mongorestore
only adds documents to the database from
the dump located in the dump/
folder if the documents have a
field name field
that holds a value of 1
. Enclose the
filter in single quotes (e.g. '
) to prevent the filter from
interacting with your shell environment.
Restore Without a Running mongod
¶
mongorestore
can write data to MongoDB data files without
needing to connect to a mongod
directly.
Example
Restore a Database Without a Running mongod
Given a set of backed up databases in the /data/backup/
directory:
/data/backup/customers
,/data/backup/products
, and/data/backup/suppliers
The following mongorestore
command restores the
products
database. The command uses the --dbpath
option to specify the path to the MongoDB
data files:
The mongorestore
imports the database backup in the
/data/backup/products
directory to the mongod
instance
that runs on the localhost interface. The mongorestore
operation imports the backup even if the mongod
is not
running.
The --journal
option ensures that
mongorestore
records all operation in the durability
journal. The journal prevents data file corruption if
anything (e.g. power failure, disk failure, etc.) interrupts the
restore operation.
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.