Back Up and Restore a Self-Managed Deployment with MongoDB Tools (original) (raw)

This tutorial describes the process for creating backups and restoring data using the command-line utilities mongorestore and mongodumpprovided with MongoDB.

To restore a backup of your self-hosted deployment to a managed MongoDB Atlas deployment, see Seed with mongorestore.

For a fully-managed backup method, use Cloud Backupsin MongoDB Atlas, which provide localized backup storage using the native snapshot functionality of the cluster's cloud service provider.

The mongorestore and mongodump utilities work with BSON data dumps, and are useful for creating backups of small deployments. For resilient and non-disruptive backups, use file system snapshotsor block-level disk snapshots withCloud Backups from MongoDB Atlas.

Note

Back Up Sharded Clusters with MongoDB Atlas

Because mongodump and mongorestore operate by interacting with a running mongod instance, they can impact the performance of your running database. Not only do the tools create traffic for a running database instance, they also force the database to read all data through memory. When MongoDB reads infrequently used data, it can evict more frequently accessed data, causing a deterioration in performance for the database's regular workload.

When backing up your data with MongoDB's tools, consider the following guidelines:

• Label files so that you can identify the contents of the backup as well as the point in time that the backup reflects.
• Use an alternative backup strategy such asFilesystem Snapshotsor Cloud Backups in MongoDB Atlasif the performance impact of mongodump and mongorestore is unacceptable for your use case.
• To ensure mongodump can take a consistent backup of a replica set, you must either use the--oplog option to capture writes received during backup operations or stop all writes to the replica set for the duration of the backup.
  For sharded cluster replica sets, seeBack Up a Self-Managed Sharded Cluster with a Database Dump.
• Ensure that your backups are usable by restoring them to a test MongoDB deployment.
• To help reduce the likelihood of inconsistencies in a sharded cluster backup, you must stop the balancer, stop all write operations, and stop any schema transformations for the duration of the backup.

See also:

mongorestore and mongodump can output data to an archive file, which is a single-file alternative to multiple BSON files. Archive files are special-purpose formats that support non-contiguous file writes. They enable concurrent backups from MongoDB, as well as restores to MongoDB. Using archive files optimizes disk I/O while backup and restore operations execute.

You can also output archive files to the standard output (stdout). Writing to the standard output allows for data migration over networks, reduced disk I/O footprint, and concurrency gains in both the MongoDB tools and your storage engine.

For more information on archive files, see the--archive option.

Backups provide a snapshot of the current state of the database. When you restore from a backup, the restored database doesn't include any changes made after the backup was taken, which can result in data loss.

Note

Back Up Sharded Clusters with MongoDB Atlas

mongodump excludes the content of the local database in its output.

To run mongodump against a MongoDB deployment that hasaccess control enabled, you must have privileges that grant find action for each database to back up. The built-in backup role provides the required privileges to perform backup of any and all databases.

The backup role provides additional privileges to back up the system.profilecollection that exists when running with database profiling.

The mongodump utility backs up data by connecting to a running mongod.

The utility can create a backup for an entire server, database or collection, or can use a query to backup just part of a collection.

When you run mongodump without any arguments, the command connects to the MongoDB instance on the local system (e.g. localhost) on port 27017 and creates a database backup named dump/ in the current directory.

To backup data from a mongod instance running on the same machine and on the default port of 27017, use the following command:

To specify the host and port of the MongoDB instance, you can either:

• Specify the hostname and port in the --uri string, using either anSRV orstandard connection string:

mongodump --uri="mongodb+srv://username:password@cluster0.example.mongodb.net" <additional_options>  

• Specify the hostname and port in the --host string:

mongodump --host="mongodb0.example.com:27017" <additional_options>  

• Specify the hostname and port in the --host and --port:

mongodump --host="mongodb0.example.com" --port=27017 <additional_options>  

mongodump will write BSON files that hold a copy of data accessible via the mongod listening on port 27017 of the mongodb.example.net host. See Create Backups from Non-Local mongod Instances for more information.

To specify a different output directory, you can use the --out or -o option:

mongodump --out=/opt/backup/mongodump-1

To limit the amount of data included in the database dump, you can specify --db and--collection as options tomongodump. For example:

mongodump --collection=myCollection --db=test

This operation creates a dump of the collection named myCollectionfrom the database test in a dump/ subdirectory of the current working directory.

mongodump overwrites output files if they exist in the backup data folder. Before running the mongodump command multiple times, either ensure that you no longer need the files in the output folder (the default is the dump/ folder) or rename the folders or files.

The --oplog option withmongodump collects the oplog entries and allows you to perform a backup on a live database. If you later restore the database from the backup, the database will be the same as it was when the backup process completed.

With --oplog, mongodumpcopies all the data from the source database as well as all of theoplog entries from the beginning to the end of the backup procedure. This operation, in conjunction with mongorestore --oplogReplay, allows you to restore a backup that reflects the specific moment in time that corresponds to when mongodump completed creating the dump file.

The --host and--port options formongodump allow you to connect to and backup from a remote host. Consider the following example:

mongodump \

   --host=mongodb1.example.net \

   --port=3017 \

   --username=user \

   --password="pass" \

   --out=/opt/backup/mongodump-1

On any mongodump command you may, as above, specify username and password credentials to specify database authentication.

Note

Back Up Sharded Clusters with MongoDB Atlas

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.profilecollection data and you run mongorestore without the--oplogReplay option.

If the backup data includes system.profile collection data or you run with--oplogReplay, you need additional privileges:

The mongorestore utility restores a binary backup created bymongodump. By default, mongorestore looks for a database backup in the dump/ directory.

The mongorestore utility restores data by connecting to a running mongod directly.

mongorestore can restore either an entire database backup or a subset of the backup.

Note

All MongoDB collections haveUUIDs by default. When MongoDB restores collections, the restored collections retain their original UUIDs. When restoring a collection where no UUID was present, MongoDB generates a UUID for the restored collection.

For more information on collection UUIDs, see Collections.

To use mongorestore to connect to an activemongod, use a command with the following prototype form:

mongorestore --uri <connection string> <path to the backup>

Consider the following example:

mongorestore /opt/backup/mongodump-1

Here, mongorestore imports the database backup in the /opt/backup/mongodump-1 directory to the mongod instance running on the localhost interface on the default port 27017.

To capture writes that may occur while mongodump is running, usemongodump --oplog. mongodump creates an oplog.bsonfile with oplog entries for each write that occurred during the run. You can apply the oplog operations with mongorestore --oplogReplay.

For examples, see mongodump Examples andmongorestore Examples.

All of the data from the oplog.bson file is restored.

mongorestore --oplogReplay doesn't allow you to restore data to an arbitrary point in time. Use mongorestore --oplogReplay to ensure the restored data is up to date with any writes that occurred during the mongodump --oplog run.

Note

You may also consider using the mongorestore --objcheckoption to check the integrity of objects while inserting them into the database, or you may consider the mongorestore --drop option to drop each collection from the database before restoring from backups.

By default, mongorestore connects to a MongoDB instance running on the localhost interface and on the default port (27017). If you want to restore to a different host or port, use the --host and --port options.

The following example that specifies the --host and --portoptions:

mongorestore --host=mongodb1.example.net --port=3017

If restoring to an instance that enforces access control, include the--username and the--authenticationDatabase as well. Omit the--password option to havemongorestore prompt for the password:

mongorestore \

   --host=mongodb1.example.net \

   --port=3017 \

   --username=user \

   --authenticationDatabase=admin \

   /opt/backup/mongodump-1