mongorestore Behavior, Access, and Usage
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 theadmin
database. By default,mongorestore
skips this database. If you use the--db
option to set the destination database toadmin
, 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 Both the built-in roles |
--oplogReplay | To run with Grant only to users who must run |
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: