Docs Menu
Docs Home
/
MongoDB Database Tools
/
mongorestore

mongorestore Behavior, Access, and Usage

On this page

  • Behavior
  • Required Access
  • Usage in Backup Strategy
  • Learn More

Behavior

Restore to Matching Server Version

When using mongorestore to load data files created by mongodump, the MongoDB versions of your source and destination deployments must be either:

  • The same major version.

  • The same feature compatibility version.

For example, if your dump was created from a MongoDB deployment running version 4.4, the MongoDB deployment you restore to must also run version 4.4 or have its FCV set to 4.4.

To change your feature compatibility version, see setFeatureCompatibilityVersion.

Note

You can restore the BSON files generated from mongodump into MongoDB deployments running the same or newer version as the source deployment. However, restoring files into a newer version deployment is not the recommended way to upgrade your deployment. To learn how to upgrade your deployment, see the upgrade documentation.

This guarantee does not apply to metadata, archive, or oplog replay files. If you try to restore these files using different source and destination deployment versions, the mongorestore process could result in failure, silent failure, or corrupted metadata.

In addition, ensure that you are using the same version of mongorestore to load the data files as the version of mongodump that you used to create them. For example, if you used mongodump version 100.9.0 to create the dump, use mongorestore version 100.9.0 to restore it.

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 after restoring data.

Note

For MongoDB installations with featureCompatibilityVersion (fCV) set to "4.0" or earlier, creating indexes will error if an index key in an existing document exceeds the limit.

To avoid this issue, consider using hashed indexes or indexing a computed value instead. If you 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.

Exclude system.profile Collection

mongorestore does not restore the system.profile collection data.

FIPS

mongorestore automatically creates FIPS-compliant connections to a mongod/mongos that is configured to use FIPS mode.

Write Concern

If you specify write concern in both the --writeConcern option and the --uri connection string option, the --writeConcern value overrides the write concern specified in the URI string.

Time Series Collections

Starting in MongoDB 5.0, you can use mongorestore to restore timeseries collections. For details, see Restore a Time Series Collection.

Using mongorestore on Atlas Free and Shared Tier Clusters

On free (M0) and shared (M2 and M5) tier Atlas clusters, the following limitations apply:

  • You can't run mongorestore on the admin database. By default, mongorestore skips this database. If you use the --db option to set the destination database to admin, the program returns an error.

  • You can't use the following options with the mongorestore program:

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 mongorestore with the --oplogReplay option, 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.

Usage in Backup Strategy

Standalones/Replica Sets

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

Sharded Clusters

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:

Learn More

← mongorestore Compatibility and Installation
mongorestore Examples →

On this page