- Reference >
- MongoDB Package Components >
mongodump
mongodump
¶
On this page
Synopsis¶
mongodump
is a utility for creating a binary export of the
contents of a database. Consider using this utility as part an
effective backup strategy. Use
mongodump
in conjunction with mongorestore
to
restore databases.
mongodump
can read data from either mongod
or mongos
instances, in addition to reading directly from MongoDB data files
without an active mongod
.
Important
mongodump
does not dump the content of the
local
database.
Warning
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.
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.
Options¶
-
mongodump
¶
-
--help
¶
Returns a basic help and usage text.
-
--verbose
,
-v
¶
Increases the amount of internal reporting returned on the command line. Increase the verbosity with the
-v
form by including the option multiple times, (e.g.-vvvvv
.)
-
--host
<hostname><:port>
¶ Specifies a resolvable hostname for the
mongod
that you wish to use to create the database dump. By defaultmongodump
will attempt to connect to a MongoDB process running on the localhost port number27017
.Optionally, specify a port number to connect a MongoDB instance running on a port other than
27017
.To connect to a replica set, use the
--host
argument with a setname, followed by a slash and a comma-separated list of host names and port numbers. Themongodump
utility will, given the seed of at least one connected set member, connect to the primary member of that set. This option would resemble:You can always connect directly to a single MongoDB instance by specifying the host and port number directly.
-
--port
<port>
¶ Specifies the port number, if the MongoDB instance is not running on the standard port. (i.e.
27017
) You may also specify a port number using the--host
option.
-
--ipv6
¶
Enables IPv6 support that allows
mongodump
to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes, includingmongodump
, disable IPv6 support by default.
-
--ssl
¶
New in version 2.4: MongoDB added support for SSL connections to
mongod
instances in mongodump.Note
SSL support in mongodump is not compiled into the default distribution of MongoDB. See Connect to MongoDB with SSL for more information on SSL and MongoDB.
Additionally, mongodump does not support connections to
mongod
instances that require client certificate validation.Allows
mongodump
to connect tomongod
instance over an SSL connection.
-
--username
<username>
,
-u
<username>
¶ Specifies a username to authenticate to the MongoDB instance, if your database requires authentication. Use in conjunction with the
--password
option to supply a password.
-
--password
<password>
,
-p
<password>
¶ Specifies a password to authenticate to the MongoDB instance. Use in conjunction with the
--username
option to supply a username.If you specify a
--username
and do not pass an argument to--password
,mongodump
will prompt for a password interactively. If you do not specify a password on the command line,--password
must be the last argument specified.
-
--authenticationDatabase
<dbname>
¶ New in version 2.4.
Specifies the database that holds the user’s (e.g
--username
) credentials.By default,
mongodump
assumes that the database specified to the--db
argument holds the user’s credentials, unless you specify--authenticationDatabase
.See
userSource
, system.users Privilege Documents and User Privilege Roles in MongoDB for more information about delegated authentication in MongoDB.
-
--authenticationMechanism
<name>
¶ New in version 2.4.
Specifies the authentication mechanism. By default, the authentication mechanism is
MONGODB-CR
, which is the MongoDB challenge/response authentication mechanism. In MongoDB Enterprise,mongodump
also includes support forGSSAPI
to handle Kerberos authentication.See Deploy MongoDB with Kerberos Authentication for more information about Kerberos authentication.
-
--dbpath
<path>
¶ Specifies the directory of the MongoDB data files. If used, the
--dbpath
option enablesmongodump
to attach directly to local data files and copy the data without themongod
. To run with--dbpath
,mongodump
needs to restrict access to the data directory: as a result, nomongod
can access the same path while the process runs.
-
--directoryperdb
¶
Use the
--directoryperdb
in conjunction with the corresponding option tomongod
. This option allowsmongodump
to read data files organized with each database located in a distinct directory. This option is only relevant when specifying the--dbpath
option.
-
--journal
¶
Allows
mongodump
operations to use the durability journal to ensure that the export is in a valid state. This option is only relevant when specifying the--dbpath
option.
-
--db
<db>
,
-d
<db>
¶ Use the
--db
option to specify a database formongodump
to backup. If you do not specify a DB,mongodump
copies all databases in this instance into the dump files. Use this option to backup or copy a smaller subset of your data.
-
--collection
<collection>
,
-c
<collection>
¶ Use the
--collection
option to specify a collection formongodump
to backup. If you do not specify a collection, this option copies all collections in the specified database or instance to the dump files. Use this option to backup or copy a smaller subset of your data.
-
--out
<path>
,
-o
<path>
¶ Specifies a directory where
mongodump
saves the output of the database dump. By default,mongodump
saves output files in a directory nameddump
in the current working directory.To send the database dump to standard output, specify “
-
” instead of a path. Write to standard output if you want process the output before saving it, such as to usegzip
to compress the dump. When writing standard output,mongodump
does not write the metadata that writes in a<dbname>.metadata.json
file when writing to files directly.
-
--query
<json>
,
-q
<json>
¶ Provides a query to limit (optionally) the documents included in the output of
mongodump
.
-
--oplog
¶
Use this option to ensure that
mongodump
creates a dump of the database that includes a partial oplog containing operations from the duration of themongodump
operation. This oplog produces an effective point-in-time snapshot of the state of amongod
instance. To restore to a specific point-in-time backup, use the output created with this option in conjunction withmongorestore --oplogReplay
.Without
--oplog
, if there are write operations during the dump operation, the dump will not reflect a single moment in time. Changes made to the database during the update process can affect the output of the backup.--oplog
has no effect when runningmongodump
against amongos
instance to dump the entire contents of a sharded cluster. However, you can use--oplog
to dump individual shards.
-
--repair
¶
Use this option to run a repair option in addition to dumping the database. The repair option attempts to repair a database that may be in an invalid state as a result of an improper shutdown or
mongod
crash.Note
The
--repair
option uses aggressive data-recovery algorithms that may produce a large amount of duplication.
-
--forceTableScan
¶
Forces
mongodump
to scan the data store directly: typically,mongodump
saves entries as they appear in the index of the_id
field. Use--forceTableScan
to skip the index and scan the data directly. Typically there are two cases where this behavior is preferable to the default:- If you have key sizes over 800 bytes that would not be present
in the
_id
index. - Your database uses a custom
_id
field.
When you run with
--forceTableScan
,mongodump
does not use$snapshot
. As a result, the dump produced bymongodump
can reflect the state of the database at many different points in time.Important
Use
--forceTableScan
with extreme caution and consideration.- If you have key sizes over 800 bytes that would not be present
in the
Behavior¶
When running mongodump
against a mongos
instance
where the sharded cluster consists of replica sets, the read preference of the operation will prefer reads
from secondary members of the set.
Warning
Changed in version 2.2: When used in combination with fsync
or
db.fsyncLock()
, mongod
may block some
reads, including those from mongodump
, when
queued write operation waits behind the fsync
lock.
Required User Privileges¶
Note
User privileges changed in MongoDB 2.4.
The user must have appropriate privileges to read data from database
holding collections in order to use mongodump
. Consider the
following required privileges for
the following mongodump
operations:
Task | Required Privileges |
---|---|
All collections in a database except system.users . |
read . [1] |
All collections in a database, including system.users . |
read [1] and userAdmin . |
All databases. [3] | readAnyDatabase , userAdminAnyDatabase ,
and clusterAdmin . [2] |
See User Privilege Roles in MongoDB and system.users Privilege Documents for more information on user roles.
[1] | (1, 2) You may provision readWrite
instead of read . |
[2] | clusterAdmin provides the ability to
run the listDatabases command, to list all existing
databases. |
[3] | If any database runs with profiling enabled,
mongodump may need the
dbAdminAnyDatabase privilege to dump the
system.profile collection. |
Usage¶
See the Back Up and Restore with MongoDB Tools
for a larger overview of mongodump
usage. Also see the
mongorestore document for an overview of the
mongorestore
, which provides the related inverse
functionality.
The following command creates a dump file that contains only the
collection named collection
in the database named test
. In
this case the database is running on the local interface on port
27017
:
In the next example, mongodump
creates a backup of the
database instance stored in the /srv/mongodb
directory on the
local machine. This requires that no mongod
instance is
using the /srv/mongodb
directory.
In the final example, mongodump
creates a database dump
located at /opt/backup/mongodump-2011-10-24
, from a database
running on port 37017
on the host mongodb1.example.net
and
authenticating using the username user
and the password
pass
, as follows: