mongodump

macOS Sierra and Go 1.6 Incompatibility

Users running on macOS Sierra require the 3.2.10 or newer version of mongodump.

Synopsis

mongodump is a utility for creating a binary export of the contents of a database. mongodump can export data from either mongod or mongos instances.

mongodump can be a part of a backup strategy with mongorestore for partial backups based on a query, syncing from production to staging or development environments, or changing the storage engine of a standalone. However, the use of mongodump and mongorestore as a backup strategy can be problematic for sharded clusters and replica sets.

Run mongodump from the system command line, not the mongo shell.

For an overview of mongodump in conjunction with mongorestore part of a backup and recovery strategy, see Back Up and Restore with MongoDB Tools.

Behavior

Data Exclusion

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

mongodump only captures the documents in the database in its backup data and does not include index data. mongorestore or mongod must then rebuild the indexes after restoring data.

Changed in version 3.4: MongoDB 3.4 added support for read-only views. By default, mongodump only captures a view’s metadata: it does not create a binary export of the documents included in the view. To capture the documents in a view use --viewsAsCollections.

Read Preference

Replica Sets

Changed in version 3.2.0: The choice of target or targets for the --host parameter affects the read preference of mongodump when connecting to a replica set.

  • If the string passed to --host is prefixed by the replica set name, mongodump reads from the primary replica set member by default. For example:

    --host "replSet/rep1.example.net:27017,rep2.example.net:27017,rep3.example.net:27017"
    
  • If the string passed to --host contains a list of mongod instances, but does not include the replica set name as a prefix to the host string, mongodump reads from the nearest node by default. For example:

    --host "rep1.example.net:27017,rep2.example.net:27017,rep3.example.net:27017"
    

Sharded Clusters

Changed in version 3.0.5: For a sharded cluster where the shards are replica sets, mongodump no longer prefers reads from secondary members when run against the mongos instance.

For sharded clusters, specify the hostname of a mongos for the --host option. mongodump reads from the primary replica set member on each shard replica set in the cluster.

Unsharded collections in a sharded cluster are stored on a primary shard. mongodump reads from the primary replica set member on the primary shard for any unsharded collections. Note: each database has its own primary shard.

Overwrite Files

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.

Data Compression Handling

When run against a mongod instance that uses the WiredTiger storage engine, mongodump outputs uncompressed data.

Working Set

mongodump can adversely affect performance of the mongod. If your data is larger than system memory, the mongodump will push the working set out of memory.

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.

Options

Changed in version 3.0.0: mongodump removed the --dbpath as well as related --directoryperdb and --journal options. To use mongodump, you must run mongodump against a running mongod or mongos instance as appropriate.

mongodump
--help

Returns information on the options and use of mongodump.

--verbose , -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--quiet

Runs mongodump in a quiet mode that attempts to limit the amount of output.

This option suppresses:

  • output from database commands
  • replication activity
  • connection accepted events
  • connection closed events
--version

Returns the mongodump release number.

--uri <connectionString>

New in version 3.4.6.

Specify a resolvable URI connection string to connect to the MongoDB deployment.

--uri "mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]"

For more information on the components of the connection string, see the Connection String URI Format documentation.

Important

The following command-line options cannot be used in conjunction with --uri option:

Instead, specify these options as part of your --uri connection string.

--host <hostname><:port> , -h <hostname><:port>

Default: localhost:27017

Specifies a resolvable hostname for the mongod to which to connect. By default, the mongodump attempts to connect to a MongoDB instance running on the localhost on port number 27017.

To connect to a replica set, specify the replSetName and a seed list of set members, as in the following:

--host <replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

When specifying the replica set list format, mongodump always connects to the primary.

You can also connect to any single member of the replica set by specifying the host and port of only that member:

--host <hostname1><:port>

Changed in version 3.0.0: If you use IPv6 and use the <address>:<port> format, you must enclose the portion of an address and port combination in brackets (e.g. [<address>]).

Note

You cannot specify both --host and --uri.

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

Note

You cannot specify both --port and --uri.

--ipv6

Removed in version 3.0.

Enables IPv6 support and allows mongodump to connect to the MongoDB instance using an IPv6 network. Prior to MongoDB 3.0, you had to specify --ipv6 to use IPv6. In MongoDB 3.0 and later, IPv6 is always enabled.

--ssl