How to back up and restore MongoDB with mongodump and mongorestore
Back up a MongoDB database with mongodump and restore it with mongorestore, plus the flags that decide what comes back: --drop, --gzip, renaming, users.
Quick Answer
Dump one database to a single compressed file, then restore it:
mongodump --uri="mongodb://localhost:27017" --db=shop --archive=shop.archive.gz --gzip
mongorestore --uri="mongodb://localhost:27017" --archive=shop.archive.gz --gzip --drop--drop replaces the collections that are in the backup. Without it, documents that already exist are skipped, and mongorestore still exits with status 0.
What mongodump saves
mongodump connects like any client and writes each collection's documents as BSON, plus a small metadata file. Run against one database, the folder looks like this:
dump/shop/
orders.bson # the documents
orders.metadata.json # index definitions, collection options, UUID
ny_orders.metadata.json # a view: its pipeline only, no documents
prelude.json # server and tool versions| Saved | Not saved |
|---|---|
| Documents, collection options, validators | Index data (indexes are rebuilt from their definitions on restore) |
| Index definitions | Users and roles, unless you add --dumpDbUsersAndRoles |
| View definitions | A point-in-time snapshot of a busy database, unless you use --oplog on a replica set |
Because it reads through a normal connection, mongodump is right for small and medium databases, migrations and copies between environments. For large production clusters, filesystem snapshots or your provider's backups are faster to restore. To run dumps on a schedule, see automating and scheduling mongodump backups.
Folder, gzip or archive
| Command | Produces | Use it when |
|---|---|---|
--out=dump | A folder of .bson files | You want to restore single collections or inspect files |
--out=dump --gzip | The same folder, each file gzipped | Disk space matters |
--archive=file | One file | Copying or uploading a backup |
--archive=file.gz --gzip | One compressed file | Most backups |
--archive with no file name writes to standard output, so you can copy a database between servers without touching disk:
mongodump --uri="$SOURCE_URI" --db=shop --archive | mongorestore --uri="$TARGET_URI" --archive --dropRestore needs the same flags you dumped with. An archive made with --gzip must be restored with --archive=… --gzip.
Restore options that change the result
# replace what's in the backup
mongorestore --uri="$URI" --drop dump/
# restore one collection from a full dump
mongorestore --uri="$URI" --nsInclude="shop.orders" dump/
# restore under a new database name
mongorestore --uri="$URI" --nsFrom="shop.*" --nsTo="shop_copy.*" dump/
# see what would happen without writing anything
mongorestore --uri="$URI" --dryRun --drop dump/--nsInclude, --nsFrom and --nsTo work on archives too, which is how you pull one collection out of a single-file backup. They replace the older --db and --collection flags, which now print a deprecation warning.
What we found testing this
Setup: a 50,000-document orders collection (about 8.2 MB of BSON) with two secondary indexes, a view and a database user, on MongoDB 7.0 in Docker on an Apple-silicon Mac.
1. A restore where every document failed still exits 0
Restoring the dump on top of the existing data, without --drop, every insert hit a duplicate _id. mongorestore logged each one and carried on:
continuing through error: E11000 duplicate key error collection: shop.orders index: _id_ dup key: { _id: 0 }
...
0 document(s) restored successfully. 50000 document(s) failed to restore.
$ echo $?
0A backup script that only checks the exit code would report success. Add --stopOnError (exit status 1 on the first failure) or use --drop, and check the "failed to restore" count in the log.
2. --drop only drops what's in the backup
We added an extra collection after taking the dump, then restored with --drop. orders was replaced, and extra was still there afterwards. --drop makes the backed-up collections match the backup. It doesn't make the database match it.
3. Gzip: 8× smaller, about 2.4× slower
| Format | Size | Dump time |
|---|---|---|
| Folder | 8.2 MB | 103 ms |
| Folder, --gzip | 1.0 MB | 247 ms |
| Archive | 8.2 MB | 79 ms |
| Archive, --gzip | 1.0 MB | 206 ms |
Our data was repetitive, which flatters gzip. Real data usually compresses less, but it's still worth it for anything you store or upload.
4. Users come back only with two flags and the old --db syntax
A plain --db=shop dump has no users. Users live in admin.system.users, so you have to ask for them with --dumpDbUsersAndRoles. Restoring them needs --restoreDbUsersAndRoles, and that flag refused to work with --nsInclude:
$ mongorestore --restoreDbUsersAndRoles --nsInclude="shop.*" dump/
Failed: cannot use --restoreDbUsersAndRoles without a specified database
$ mongorestore --restoreDbUsersAndRoles --db=shop dump/shop # works
restoring users from dump/shop/$admin.system.users.bson5. --oplog fails on a standalone server
$ mongodump --oplog --out=dump
Failed: error getting oplog start: error getting recent oplog entry: mongo: no documents in resultA standalone server has no oplog, so a dump taken while writes are happening isn't a consistent snapshot. For a consistent backup of a busy database, run it against a replica set with --oplog and restore with --oplogReplay.
Connection and permission errors
| Message | Cause |
|---|---|
(Unauthorized) Command listCollections requires authentication | The server has access control on and no credentials were sent |
unable to authenticate using mechanism "SCRAM-SHA-256": (AuthenticationFailed) | Wrong user name or password |
unable to authenticate using mechanism "SCRAM-SHA-1": (AuthenticationFailed) | Right credentials, wrong authentication database. The URI path (/shop) became the authSource |
For the last one, add ?authSource=admin to the URI. A user needs the backup role to dump and restore to restore, or read and readWrite on the databases involved.
Frequently Asked Questions
Does mongodump lock the database?
No. It reads through a normal connection, so the database stays available. Large dumps do add read load and can push working data out of cache.
Does mongorestore restore indexes?
Yes. It rebuilds them from the definitions in the metadata files after the documents are inserted. Use --noIndexRestore to skip that and build them later.
Can I restore a dump to a different MongoDB version?
Often, but MongoDB recommends restoring to the same major version the dump came from. The prelude.json file in the dump records both the server and tool versions.
How do I back up only one collection?
Use mongodump --db=shop --collection=orders, or restore a single collection from a full dump with --nsInclude="shop.orders".
Why did mongorestore say documents failed but the job succeeded?
By default it continues through errors such as duplicate keys and exits with status 0. Use --stopOnError to make failures fail the command.