mongorestore Examples

Restore with Access Control

In the following example, mongorestore restores from /opt/backup/mongodump-2011-10-24 to a mongod instance running on port 27017 on the host mongodb1.example.net. The --uri string omits the user's password to have mongorestore prompt for the password.

mongorestore --uri="mongodb://user@mongodb1.example.net:27017/?authSource=admin" /opt/backup/mongodump-2011-10-24

Alternatively, you can specify the host, port, username, and authentication database using --host, --port, --username, and --authenticationDatabase. Omit --password to have mongorestore prompt for the password:

mongorestore --host=mongodb1.example.net --port=27017 --username=user --authenticationDatabase=admin /opt/backup/mongodump-2011-10-24

Restore a Collection

To restore a specific collection, use --nsInclude, passing in the full namespace (<database>.<collection>) of the collection.

The following example restores the collection named purchaseorders in the database test from the corresponding files located in the dump/ directory.

mongorestore --nsInclude=test.purchaseorders dump/

The mongorestore outputs the results, including the number of documents restored:

2019-06-28T19:23:42.858-0400   preparing collections to restore from
2019-06-28T19:23:42.858-0400   reading metadata for test.purchaseorders from dump/test/purchaseorders.metadata.json
2019-06-28T19:23:42.893-0400   restoring test.purchaseorders from dump/test/purchaseorders.bson
2019-06-28T19:23:42.896-0400   restoring indexes for collection test.purchaseorders from metadata
2019-06-28T19:23:42.991-0400   finished restoring test.purchaseorders (6 documents, 0 failures)
2019-06-28T19:23:42.991-0400   6 document(s) restored successfully. 0 document(s) failed to restore.

If the dump/ directory does not contain the corresponding data files for the specified namespace, no data will be restored:

2019-07-08T14:39:57.121-0400. preparing collections to restore from
2019-07-08T14:39:57.121-0400  0 document(s) restored successfully. 0 document(s) failed to restore.

Alternatively, you can restore a specific collection using the --db, --collection, and a .bson file:

mongorestore --db=test --collection=purchaseorders dump/test/purchaseorders.bson

2019-06-30T12:21:44.777-0400   checking for collection data in dump/test/purchaseorders.bson
2019-06-30T12:21:44.779-0400   reading metadata for test.purchaseorders from dump/test/purchaseorders.metadata.json
2019-06-30T12:21:44.813-0400   restoring test.purchaseorders from dump/test/purchaseorders.bson
2019-06-30T12:21:44.881-0400   restoring indexes for collection test.purchaseorders from metadata
2019-06-30T12:21:44.987-0400   finished restoring test.purchaseorders (6 documents, 0 failures)
2019-06-30T12:21:44.987-0400   6 document(s) restored successfully. 0 document(s) failed to restore.

Restore a Queryable Encryption Enabled Collection

Queryable Encryption adds a __safeContent__ field to documents in an encrypted collection and blocks insert and update operations on those documents unless document validation is disabled. To restore a collection that includes encrypted fields, use --bypassDocumentValidation.

mongodump exports a Queryable Encryption enabled collection's associated metadata collections. Running mongorestore restores these collections as well.

mongorestore --db=test --collection=personaldata dump/test/personaldata.bson --bypassDocumentValidation

Restore Collections Using Wild Cards

--nsInclude and --nsExclude support specifying the namespaces you wish to include or exclude from a restore operation using asterisks as wild cards.

The following example restores the documents in the dump/ sub-directory of the current directory that match the specified namespace pattern. The --nsInclude statement specifies to only restore documents in the transactions database while --nsExclude instructs mongorestore to exclude collections whose names end with _dev. mongorestore restores data to the mongod instance running on the localhost interface on port 27017.

mongorestore --nsInclude='transactions.*' --nsExclude='transactions.*_dev' dump/

Change Collection Namespaces during Restore

To change the namespace of the collection that you are restoring, use the --nsFrom and --nsTo options.

The --nsFrom and --nsTo options support using asterisks as wild cards and support using dollar signs to delimit "wild card" variables to use in the replacement.

Consider a database data that you have exported to a dump/ directory using mongodump. The data database contains the following collections:

• sales_customer1

• sales_customer2

• sales_customer3

• users_customer1

• users_customer2

• users_customer3

Using --nsFrom and --nsTo, you can restore the data into different namespaces. The following operation

• restores the sales_<customerName> collections in the data database to sales collections in the <customerName> database, and

• restores the users_<customerName> collections to users collections in the <customerName> database.

mongorestore --nsInclude="data.*" --nsFrom="data.$prefix$_$customer$" --nsTo="$customer$.$prefix$"

Copy/Clone a Database

Starting in version 4.2, MongoDB removes the deprecated copydb command and clone command.

As an alternative, users can use mongodump and mongorestore (with the mongorestore options --nsFrom and --nsTo).

For example, to copy the test database from a local instance running on the default port 27017 to the examples database on the same instance, you can:

1. Use mongodump to dump the test database to an archive mongodump-test-db:

   mongodump --archive="mongodump-test-db" --db=test

2. Use mongorestore with --nsFrom and --nsTo to restore (with database name change) from the archive:

   mongorestore --archive="mongodump-test-db" --nsFrom="test.*" --nsTo="examples.*"

Restore from an Archive File

To restore from an archive file, run mongorestore with the new --archive option and the archive filename.

mongorestore --archive=test.20150715.archive

mongorestore --archive=test.20150715.archive  --nsInclude="test.*"

Restore from Compressed Data

mongorestore can restore from compressed files or compressed archive files created by mongodump.

To restore from a dump directory that contains compressed files, run mongorestore with the --gzip option. For example, the following operation restores the test database from the compressed files located in the default dump directory:

mongorestore --gzip  --nsInclude="test.*" dump/

To restore from a compressed archive file, run mongorestore with the --gzip option and the --archive option. For example, the following operation restores the test database from the archive file test.20150715.gz.

mongorestore --gzip --archive=test.20150715.gz --nsInclude="test.*"

To change the namespace of the collection that you are restoring, use the --nsFrom and --nsTo options with the --gzip option.

mongorestore --gzip --nsFrom="data.$prefix$_$customer$" --nsTo="$customer$.$prefix$"

Restore a Time Series Collection

Use mongosh to create a time series collection. This example uses the default test database:

db.createCollection(
   "weather",
   {
      timeseries: {
         timeField: "timestamp",
         metaField: "metadata",
         granularity: "hours"
      }
   }
)

Insert time series documents into the collection:

db.weather.insertMany( [
   {
      "metadata": { "sensorId": 5578, "type": "temperature" },
      "timestamp": ISODate("2021-05-18T00:00:00.000Z"),
      "temp": 12
   },
   {
      "metadata": { "sensorId": 5578, "type": "temperature" },
      "timestamp": ISODate("2021-05-18T04:00:00.000Z"),
      "temp": 11
   },
   {
      "metadata": { "sensorId": 5578, "type": "temperature" },
      "timestamp": ISODate("2021-05-18T08:00:00.000Z"),
      "temp": 11
   }
] )

From your terminal, use mongodump to export the time series collection to the dump/test directory. This commands adds system.buckets.weather.bson and weather.metadata.json to the directory:

mongodump --db=test

Use mongorestore to restore the data to the mongorestore.weather namespace:

mongorestore --host localhost --port 27017 --nsFrom="test.*" --nsTo="mongorestore.*" dump/

Connect to a MongoDB Atlas Cluster using AWS IAM Credentials

To connect to a MongoDB Atlas cluster that has been configured to support authentication via AWS IAM credentials, provide a connection string to mongorestore similar to the following:

mongorestore 'mongodb+srv://<aws access key id>:<aws secret access key>@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' <other options>

Connecting to Atlas using AWS IAM credentials in this manner uses the MONGODB-AWS authentication mechanism and the $external authSource, as shown in this example.

If using an AWS session token, as well, provide it with the AWS_SESSION_TOKEN authMechanismProperties value, as follows:

mongorestore 'mongodb+srv://<aws access key id>:<aws secret access key>@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<aws session token>' <other options>

: / ? # [ ] @

Alternatively, the AWS access key ID, secret access key, and optionally session token can each be provided outside of the connection string using the --username, --password, and --awsSessionToken options instead, like so:

mongorestore 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' --username <aws access key id> --password <aws secret access key> --awsSessionToken <aws session token> <other options>

When provided as command line parameters, these three options do not require percent encoding.

You may also set these credentials on your platform using standard AWS IAM environment variables. mongorestore checks for the following environment variables when you use the MONGODB-AWS authentication mechanism:

• AWS_ACCESS_KEY_ID

• AWS_SECRET_ACCESS_KEY

• AWS_SESSION_TOKEN

If set, these credentials do not need to be specified in the connection string or through their explicit options.

The following example sets these environment variables in the bash shell:

export AWS_ACCESS_KEY_ID='<aws access key id>'
export AWS_SECRET_ACCESS_KEY='<aws secret access key>'
export AWS_SESSION_TOKEN='<aws session token>'

Syntax for setting environment variables in other shells will be different. Consult the documentation for your platform for more information.

You can verify that these environment variables have been set with the following command:

env | grep AWS

Once set, the following example connects to a MongoDB Atlas cluster using these environment variables:

mongorestore 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS'  <other options>

Create and Restore Consistent Backup Files

To create a consistent mongodump backup file using oplog entries, use the mongodump --oplog option. To restore data from the backup file, use the mongorestore --oplogReplay option.

The oplog contains the history of database write operations.

mongodump outputs:

• Collection documents, metadata, and options.

• Index definitions.

• Writes that occur during the mongodump run, if --oplog is specified.

Learn More

• mongorestore

• mongorestore Compatibility and Installation

• Behavior

• Back Up and Restore a Self-Managed Deployment with MongoDB Tools

• Back Up a Self-Managed Sharded Cluster with a Database Dump

• mongosync utility for cluster to cluster migrations

• Migrate or import data in Atlas

• Back up, restore, and archive data in Atlas