mongorestore

macOS Sierra and Go 1.6 Incompatibility

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

Synopsis

The mongorestore program loads data from either a binary database dump created by mongodump or the standard input (starting in version 3.0.0) into a mongod or mongos instance.

For an overview of mongorestore usage, see Back Up and Restore with MongoDB Tools.

Syntax

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

mongorestore [options] [<directory>/<BSON file>]

For example, to restore from a dump directory to a local mongod instance running on port 27017:

mongorestore  dump/

As mongorestore restores from the dump/ directory, it creates the database and collections as needed and logs its progress:

2019-07-13T10:05:40.353-0400   preparing collections to restore from
2019-07-13T10:05:40.386-0400   reading metadata for test.bakesales from dump/test/bakesales.metadata.json
2019-07-13T10:05:40.403-0400   reading metadata for test.salaries from dump/test/salaries.metadata.json
2019-07-13T10:05:40.434-0400   restoring test.bakesales from dump/test/bakesales.bson
2019-07-13T10:05:40.464-0400   restoring test.salaries from dump/test/salaries.bson
2019-07-13T10:05:40.473-0400   no indexes to restore
2019-07-13T10:05:40.473-0400   finished restoring test.bakesales (21 documents)
2019-07-13T10:05:40.490-0400   no indexes to restore
2019-07-13T10:05:40.491-0400   finished restoring test.salaries (10 documents)
2019-07-13T10:05:40.491-0400   restoring users from dump/admin/system.users.bson
2019-07-13T10:05:40.559-0400   restoring roles from dump/admin/system.roles.bson
2019-07-13T10:05:40.711-0400   done

You can also restore a specific collection or collections from the dump/ directory. For example, the following operation restores a single collection from corresponding data files in the dump/ directory:

mongorestore --nsInclude test.purchaseorders dump/

If the dump/ directory does not contain the corresponding data file for the specified namespace, no data will be restored. For example, the following specifies a collection namespace that does not have a corresponding data in the dump/ directory:

mongorestore --nsInclude foo.bar dump/

The mongorestore outputs the following messages:

2019-07-13T10:06:36.095-0400   preparing collections to restore from
2019-07-13T10:06:36.095-0400   done

For more examples, see Examples.

For more information on the options and arguments, see Options.

Behavior

Insert Only

mongorestore can create a new database or add data to an existing database. However, mongorestore performs inserts only and does not perform updates. That is, if restoring documents to an existing database and collection and existing documents have the same value _id field as the to-be-restored documents, mongorestore will not overwrite those documents.

Rebuild Indexes

mongorestore recreates indexes recorded by mongodump.

Note

Starting in MongoDB 2.6, creating indexes will error if an index key in an existing document exceeds the limit. See Enforce Index Key Length Limit for more information and solution.

If you have an existing data set that violates this limit but want to resolve the index issue after restoring the data, you can disable the default index key length validation on the target database by setting the mongod instance’s failIndexKeyTooLong parameter to false.

Version Compatibility

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.

Exclude system.profile Collection

mongorestore does not restore the system.profile collection data.

Required Access

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 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.

Both the built-in roles dbAdmin and dbAdminAnyDatabase provide the additional privileges.

--oplogReplay

To run with --oplogReplay, create a user-defined role that has anyAction on anyResource.

Grant only to users who must run mongorestore with --oplogReplay.

Options

Changed in version 3.0.0: mongorestore removed the --filter, --dbpath, and the --noobjcheck options.

mongorestore
--help

Returns information on the options and use of mongorestore.

--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 mongorestore 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 mongorestore 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:[email protected]]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 mongorestore 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, mongorestore 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