Back Up and Restore with MongoDB Tools
On this page
This tutorial describes the process for creating backups and restoring data using the utilities provided with MongoDB.
Note
MongoDB Atlas
MongoDB Atlas, the official MongoDB cloud service, provides 2 fully-managed methods for backups:
Continuous Backups, which take incremental backups of data in your cluster, ensuring your backups are typically just a few seconds behind the operational system. Atlas continuous backups allow you to restore from stored snapshots or from a selected point in time within the last 24 hours. You can also query a continuous backup snapshot.
Cloud Provider Snapshots, which provide localized backup storage using the native snapshot functionality of the cluster's cloud service provider.
Considerations
Deployments
The mongodump
and mongorestore
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.
Note
mongodump
and mongorestore
cannot be part of a backup strategy for 4.2+ sharded clusters
that have sharded transactions in progress, as backups created with
mongodump
do not maintain the atomicity guarantees
of transactions across shards.
For 4.2+ sharded clusters with in-progress sharded transactions, use one of the following coordinated backup and restore processes which do maintain the atomicity guarantees of transactions across shards:
Performance Considerations
Because mongodump
and mongorestore
operate by
interacting with a running mongod
instance, they can impact
the performance of your running database. Not only do the tools 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 evict more frequently accessed data, causing a deterioration
in performance for the database's regular workload.
When backing up your data with MongoDB's tools, consider the following guidelines:
Label files so that you can identify the contents of the backup as well as the point in time that the backup reflects.
Use an alternative backup strategy such as Filesystem Snapshots or MongoDB Cloud Manager if the performance impact of
mongodump
andmongorestore
is unacceptable for your use case.Use
--oplog
to capture incoming write operations during the {{out_tool}} operation to ensure that the backups reflect a consistent data state.Ensure that your backups are usable by restoring them to a test MongoDB deployment.
Tip
See also:
MongoDB Backup Methods and MongoDB Cloud Manager Backup documentation for more information on backing up MongoDB instances. Additionally, consider the following reference documentation for the MongoDB Database 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 MongoDB Cloud Manager or file system snapshots are unavailable.
Procedures
Back Up a Database with mongodump
Note
mongodump
and mongorestore
cannot be part of a backup strategy for 4.2+ sharded clusters
that have sharded transactions in progress, as backups created with
mongodump
do not maintain the atomicity guarantees
of transactions across shards.
For 4.2+ sharded clusters with in-progress sharded transactions, use one of the following coordinated backup and restore processes which do maintain the atomicity guarantees of transactions across shards:
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.
The backup
role provides additional privileges to back
up the system.profile
collection that exists when running with database profiling.
Basic mongodump
Operations
The mongodump
utility backs up data by connecting to a
running 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 command
connects to the MongoDB instance on the local system
(e.g. localhost
) on port 27017
and creates a
database backup named dump/
in the current directory.
To backup data from a mongod
instance
running on the same machine and on the default port of 27017
,
use the following command:
mongodump
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=/opt/backup/mongodump-1
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.
Create Backups Using Oplogs
The --oplog
option with
mongodump
collects the oplog entries and allows
you to perform a backup on a live database. If you later restore the
database from the backup, the database will be the same as it was when
the backup process completed.
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-1
On any mongodump
command you may, as above, specify username
and password credentials to specify database authentication.
Restore a Database with mongorestore
Note
mongodump
and mongorestore
cannot be part of a backup strategy for 4.2+ sharded clusters
that have sharded transactions in progress, as backups created with
mongodump
do not maintain the atomicity guarantees
of transactions across shards.
For 4.2+ sharded clusters with in-progress sharded transactions, use one of the following coordinated backup and restore processes which do maintain the atomicity guarantees of transactions across shards:
Access Control
To restore data to a MongoDB deployment that has access control enabled, the restore
role provides
the necessary privileges to restore data from backups if the data does
not include system.profile
collection data and you run mongorestore
without the
--oplogReplay
option.
If the backup data includes system.profile
collection data or you run with
--oplogReplay
, you need
additional privileges:
system.profile | If the backup data includes Both the built-in roles |
--oplogReplay | To run with Grant only to users who must run |
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
directly.
mongorestore
can restore either an entire database backup
or a subset of the backup.
Note
New in version 3.6:
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 use mongorestore
to connect to an active
mongod
, use a command with the following prototype form:
mongorestore --port=<port number> <path to the backup>
Consider the following example:
mongorestore /opt/backup/mongodump-1
Here, mongorestore
imports the database backup in
the /opt/backup/mongodump-1
directory to the mongod
instance
running 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, 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 and on the
default port (27017
). If you want to restore to a different host or
port, use the --host
and --port
options.
The following example that specifies the --host
and --port
options:
mongorestore --host=mongodb1.example.net --port=3017
If restoring to an instance that enforces access control, include the
--username
and the
--authenticationDatabase
as well. Omit the
--password
option to have
mongorestore
prompt for the password:
mongorestore \ --host=mongodb1.example.net \ --port=3017 \ --username=user \ --authenticationDatabase=admin \ /opt/backup/mongodump-1