mongorestore

Import a BSON data dump from a directory to a MongoDB database

$ mongorestore --db [database_name] [path/to/directory]

$ mongorestore --host [database_host:port] --db [database_name] --username [username] [path/to/directory] --password

$ mongorestore --db [database_name] [path/to/file]

$ mongorestore --host [database_host:port] --db [database_name] --username [username] [path/to/file] --password

mongorestore [options] [<path-to-dump-directory-or-archive>]

--help
    Displays a help message for the command and exits.

--version
    Returns the `mongorestore` release number and exits.

--host <hostname>
    Specifies the hostname or IP address of the MongoDB instance to connect to. Default is localhost.

--port <port>
    Specifies the port number of the MongoDB instance to connect to. Default is 27017.

--username <username>
    Specifies a username to authenticate to the MongoDB instance.

--password <password>
    Specifies a password to authenticate to the MongoDB instance. If not provided, `mongorestore` prompts for it.

--authenticationDatabase <dbname>
    Specifies the database where the user is defined. Used with --username and --password.

--db <database>
    Specifies the database to restore. If not specified, all databases in the dump directory are restored.

--collection <collection>
    Specifies the collection to restore. Requires --db to be specified.

--drop
    Drops each collection from the target database before restoring the collection from the dump files. This ensures a clean restore.

--archive <file.archive>
    Restores from a `mongodump` archive file created with the --archive option. Cannot be used with --dir.

--gzip
    Decompresses gzipped files produced by `mongodump --gzip` during the restore process.

--dir <directory>
    Specifies the BSON dump directory to restore from. By default, `mongorestore` looks for a directory named dump in the current working directory.

--oplogReplay
    Replays the oplog from the `oplog.bson` file found in the dump directory (or archive) to ensure point-in-time recovery. Requires a replica set backup.

--numParallelCollections <N>
    Restores collections in parallel, allowing for faster restore times for large datasets. Specify the number of collections to restore concurrently.

--noIndexRestore
    Prevents `mongorestore` from recreating indexes after restoring data. Indexes will need to be built manually afterwards.

--nsInclude <namespace_regex>
    Includes only the namespaces that match the provided regex during the restore process. A namespace is a database and collection name, e.g., mydb.mycollection.

--nsExclude <namespace_regex>
    Excludes the namespaces that match the provided regex during the restore process.

The `mongorestore` utility is an essential command-line tool used to restore data from a MongoDB database backup created by `mongodump`. It reads BSON data (Binary JSON) from a specified dump directory or a compressed archive file and writes it to a running MongoDB instance. This tool is crucial for disaster recovery, migrating data between MongoDB instances, or simply restoring a specific database or collection for development and testing purposes. `mongorestore` intelligently recreates collections, indexes, and documents, allowing granular control over the restore process through various options like dropping existing data, replaying the oplog for point-in-time recovery, or restoring only specific namespaces. It can also decompress gzipped backup files on the fly, making it flexible for various backup strategies.

Version Compatibility: Always ensure that the `mongorestore` utility version is compatible with the MongoDB server version you are restoring to. It's generally recommended to use a `mongorestore` version that is the same or slightly newer than the target MongoDB server version.

Disk Space: The target MongoDB server requires sufficient disk space to accommodate the restored data, including indexes.

Permissions: The user running `mongorestore` must have read access to the backup files/directory and appropriate write permissions on the target MongoDB instance.

--drop Option: Use the --drop option with caution, as it permanently deletes existing collections before restoring them, leading to data loss if the backup is incomplete or invalid.

Oplog Replay: Point-in-time recovery using --oplogReplay only works if the backup was taken from a replica set and includes the oplog.bson file.

When connecting to a remote MongoDB instance, always consider using TLS/SSL encryption (--tls, --tlsCAFile, etc.) to secure data in transit. Ensure that the MongoDB user specified with --username has only the necessary roles and permissions for restoring data (e.g., `restore` role).

For very large datasets, using the --numParallelCollections option can significantly reduce restore times by importing multiple collections concurrently. Also, ensuring the target MongoDB server has adequate hardware resources (CPU, RAM, fast I/O) is critical for optimal restore performance. In some extreme cases for initial bulk loads, temporarily disabling journaling on the target MongoDB instance can speed up restores, but this is highly risky and should only be done with extreme caution and understanding of data durability implications.

`mongorestore` is a foundational component of the MongoDB Database Tools, which have been an integral part of the MongoDB ecosystem since its early days. Initially bundled with the core MongoDB server distribution, these tools, including `mongorestore`, were later separated into a standalone package. This decoupling allowed for independent development and release cycles, enabling quicker updates and bug fixes for the tools without requiring a full MongoDB server upgrade. Over time, `mongorestore` has evolved to support new MongoDB features, improve performance (e.g., parallel collection restores), and handle various backup formats like gzipped files and archives, solidification its role as the primary utility for restoring MongoDB data.

mongodump(1), mongo(1), mongosh(1), mongostat(1), mongotop(1)