• Back Up and Restore Deployments >
• Restore MongoDB Deployments >
• Restore a Single Database

Restore a Single Database

Backup snapshots contain a complete copy of your mongod data directory. You may want to restore some of the data in a snapshot.

To restore a single database or a collection from a snapshot, you can use the Queryable Backup to export a single database or collection to restore to the target deployment.

You can also manually Restore a Database or Collection from a Manually Created Backup Instance.

Changed in Ops Manager 3.6: Point-in-Time Restores

Prior to 3.6, the Backup Daemon created the complete point- in-time restore on its host. With 3.6, you download a client-side tool along with your snapshot. This tool downloads and applies the oplog to a snapshot on your client system. This reduces network and storage needs for your Ops Manager deployment.

Considerations

Before you attempt a restore, ensure the host for your target deployment has sufficient storage space for the restore files and the restored database, plus additional space for dataset growth. Use db.stats() to find the current database size.

Restore a Database or Collection from Queryable Backup

You can use a queryable backup snapshot to export data for a database or a collection and restore to the target deployment. The following procedure connects to the queryable backup instance via Ops Manager-provided tunnel [1].

1

Go to Backup view and click the Overview tab.

For the deployment whose backup you want to query, click the ellipsis button under Options column and select Query.

You can also click the deployment to view its snapshots and click the Query button under the Actions column.

2

Open a Backup Tunnel to the Queryable Snapshot.

1. Select the snapshot to query and click Next.

2. Start the process to query a snapshot. You will be prompted for 2-factor verification.

3. Select Backup Tunnel as the connection method to the queryable snapshot. [1]

4. Select your platform and download.

5. Uncompress the downloaded file.

6. Open a terminal or command prompt and go to the uncompressed <tunnel> directory. Run the executable to start the tunnel.

   The default port for the tunnel is 27017. To change the port, use the --local flag, as in the following example:

   copy

   ./<tunnel executable> --local localhost:27020
   

   Note

   If you change the port, you must include the port information when connecting.

3

Use mongodump to export a single database or collection from the queryable backup.

To export the data for a database,

Include the following mongodump options to connect to the tunnel [1]:

• --port set to the port for the tunnel

• --db set to the name of the database to export

• --out set to an empty directory to output the data dump.

  Important

  Ensure that the user running mongodump can write to the specified directory.

copy

mongodump --port <port for tunnel> --db <single-database> --out <data-dump-path>

For example, to connect to a tunnel running on port 27020 to dump out data from the test database to /mydata/restoredata/ directory:

copy

mongodump --port 27020 --db test --out /mydata/restoredata/

mongodump outputs the test database files into the /mydata/restoredata/test/ directory.

If the mongodump is not in your PATH, specify the path for the tool.

To export the data for a collection,

include the following options to connect to the tunnel [1]:

• --port set to the port for the tunnel.

• --db set to the name of the database to export.

• --collection for a single collection.

• --out set to an empty directory to output the data dump.

  Important

  Ensure that the user running mongodump can write to the specified directory.

copy

mongodump --port <port for tunnel> --db <single-database> --collection <collection-name> --out <data-dump-path>

Example

To connect to a tunnel running on port 27020 to dump out data from the restaurants collection from test database to /mydata/restoredata/ directory:

copy

mongodump --port 27020 --db test --collection restaurants --out /mydata/restoredata/

mongodump outputs the restaurants collection data into the /mydata/restoredata/test/restaurants.bson file.

4

Use mongorestore to restore the single database or collection.

To restore a single database,

Include the following mongorestore options:

• --port set to the port of the destination cluster.
• --db set to the name of the destination database.

Optionally, you can include --drop to drop the database in the destination cluster if the database already exists.

copy

mongorestore --port <port> --db <destination database> <data-dump-path/database> --drop

To restore a single collection,

Include the following mongorestore options:

• --port set to the port of the destination cluster.
• --db set to the name of the destination database.

Optionally, you can include --drop to drop the collection in the destination cluster if the collection already exists.

copy

mongorestore --port <port> --db <destination database> --collection <collection-name> <data-dump-path/dbname/collection.bson> --drop

Example

To restore from the /mydata/restoredata/test/restaurants.bson data file to a new collection rest2 in the test2 database:

copy

mongorestore --port 27017 --db test2 --collection rest2 /mydata/restoredata/test/restaurants.bson --drop

The example assumes that the destination replica set’s primary or the destination sharded cluster’s mongos listens on port 27017.

5

Terminate the queryable instance.

Once you have finished, you can terminate the queryable instance:

1. Go to the Restore History and hover over the Status column for the deployment item.
2. Click Cancel.

[1]	(1, 2, 3, 4, 5, 6, 7) Alternatively, instead of connecting via the tunnel, you can connect directly to the queryable backup, using the X.509 PEM files provided. If connecting directly to the queryable backup, you must specify the hostname and port, the TLS/SSL option, and the X.509 certificates.

Restore a Database or Collection from a Manually Created Backup Instance

Prerequisites

Restoring from Encrypted Backup

To restore from an encrypted snapshot, the snapshot and target head database must have been encrypted using the same KMIP master key. The Backup Daemon host that serves the target head database must either use an existing certificate or provision a new certificate that was generated using this master key.

If the snapshot is encrypted, the restore panel displays the KMIP master key id and the KMIP server information. You can also find the information when you view the snapshot itself as well as in the restoreInfo.txt file.

Secure Copy (SCP) Delivery

SCP Restore Deprecated

Restore delivery via SCP is a deprecated feature. This feature will be removed in Ops Manager 4.0.

Important

You need to generate a key pair before using SCP. SCP transfers files faster than HTTP.

Note

Microsoft Windows does not include SCP. Installing SCP is outside the scope of this manual.

Select and Prepare a Snapshot

1

Click Backup, then the Overview tab.

2

Click the deployment then click Restore or Download.

3

Select the restore point.

Choose the point from which you want to restore your backup.

Restore Type	Description	Action
Snapshot	Allows you to choose one stored snapshot.	Select an existing snapshot to restore.
Point In Time	Creates a custom snapshot that includes all operations up to but not including the selected time. By default, the oplog stores 24 hours of data. Example If you select 12:00, the last operation in the restore is 11:59:59 or earlier. Important You cannot perform a PIT restore that covers any time prior to the latest backup resync. For the conditions that cause a resync, see Resync a Backup.	Select a Date and Time.
Oplog Timestamp	Creates a custom snapshot based on the timestamp of an oplog entry (its ts field). Ops Manager includes all operations up to and including the time of the timestamp. The oplog entry’s ts field is a BSON timestamp and has two components: the timestamp and the increment.	Type the following: Timestamp The value in seconds since the Unix epoch. Increment An incrementing ordinal for operations within a given second.

Click Next.

4

Choose how to restore the files.

Choose to restore the snapshot to an existing MongoDB instance or download a copy of the data.

To restore to an existing instance, click Choose Cluster to Restore to.

1. Complete the following fields:

   Field	Action
   Project	Select a project to which you want to restore the snapshot.
   Cluster to Restore to	Select a cluster to which you want to restore the snapshot. Warning Automation removes all existing data from the cluster. All backup data and snapshots for the existing cluster are preserved.

2. Click Restore.

   Ops Manager notes how much storage space the restore requires.

Important

You can skip the remainder of this page.

To download the data, click Download.

You can choose to download a copy using HTTPS or have Ops Manager send you a copy using SCP.

• Click Pull via Secure HTTP, then follow the procedure to Retrieve a Snapshot using HTTPS, or
• Click Push via Secure Copy then follow the procedure to Send Snapshot using SCP.

Retrieve a Snapshot using HTTPS

1

Configure the snapshot download.

1. Configure the following download options:

   Pull Restore Usage Limit	Select how many times the link can be used. If you select No Limit, the link is re-usable until it expires.
   Restore Link Expiration (in hours)	Select the number of hours until the link expires. The default value is 1.

2. Click Finalize Request.

3. If you use 2FA, Ops Manager prompts you for your 2FA code. Enter your 2FA code, then click Finalize Request.

2

Retrieve the snapshot.

The restore panel shows the restore point type and time, the delivery method, and the download link once Ops Manager has generated it.

By default, this link is available for an hour and can be used just once. To download the snapshot:

1. If you closed the restore panel, click Backup, then Restore History.
2. When the restore job completes, click (get link) for the restore.
3. Click:
   • The copy button to the right of the link to copy the link to use it later, or
   • Download to download the snapshot immediately.

Extra step for point-in-time restores

For point-in-time and oplog timestamp restores, additional instructions are shown. The final step shows the full command you must run using the MBRU. It includes all of the necessary options to ensure a full restore.

Select and copy the mongodb-backup-restore-util command provided under Run Binary with PIT Options.

Important

Skip to Restore the Database.

Send Snapshot using SCP

Direct Ops Manager to copy the restore files to your server via SCP.

1

Configure how to secure copy the data.

1. Select from the following options:

   Format	Select the format in which you want to receive the restore files: Individual DB Files Transfers individual MongoDB data files that Ops Manager produces directly to the target directory. Archive Transfers MongoDB data files in a single archive (tar or tar.gz) that you must extract before restoring the data files to a working directory. This option displays only if the archive size can be calculated. With Archive delivery, you need sufficient storage space on the destination host for both the archive and the extracted files.
   SCP Host	Type the hostname of the host to receive the files.
   SCP Port	Type the port of the host to receive the files.
   SCP User	Type the username used to access to the host.
   Auth Method	Select whether to use a username and password or an SSH certificate to authenticate to the host.
   Password	Type the user password used to access to the host.
   Passphrase	Type the SSH passphrase used to access to the host.
   Target Directory	Type the absolute path to the directory on the host to which to copy the restore files.

2. Click Finalize Request.

3. If you use 2FA, Ops Manager prompts you for your 2FA code. Enter your 2FA code, then click Finalize Request.

2

Retrieve the snapshot.

The restore panel shows the restore point type and time, the delivery method, and the download link once Ops Manager has generated it.

The files are copied to the host directory you specified. To verify that the files are complete, see how to validate a secure copy restore.

Extra step for point-in-time restores

For point-in-time and oplog timestamp restores, additional instructions are shown. The final step shows the full command you must run using the MBRU. It includes all of the necessary options to ensure a full restore.

Select and copy the mongodb-backup-restore-util command provided under Run Binary with PIT Options.

Restore the Database

The following examples use:

• 27017 as the port for a running MongoDB instance that receives the restored backup.
• 27018 as the port for the temporary MongoDB instance that uses the snapshot to export the single database.

1

Restore the snapshot data files to the destination host.

Extract the snapshot archive to a temporary location where a temporary mongod instance can access the archive contents. Use a different data directory than any other database running on the host.

Example

copy

tar -xvf {backupRestoreName}.tar.gz
mv {backupRestoreName} {temp-database-path}

2

Start a new, temporary MongoDB instance.

This temporary instance must be on a new port using the extracted backup snapshot as the dbpath.

Ensure the user executing the mongod can read, write and execute code in the directory specified with dbpath.

Example

copy

mongod --port 27018 --dbpath {temp-database-path} \
  --logpath {temp-database-path}/mongodb.log --fork

3

Run the MongoDB Backup Restore Utility (Point-in-Time Restore Only).

1. Download the MongoDB Backup Restore Utility to your host.

   Note

   If you closed the restore panel, click Backup, then More and then Download MongoDB Backup Restore Utility.

2. Run the MongoDB Backup Restore Utility on your destination host.

   Pre-configured MBRU command

   Ops Manager provides the mongodb-backup-restore-util with the appropriate options for your restore on the restore panel under Run Binary with PIT Options.

   Select and copy the mongodb-backup-restore-util command provided.

   copy

   ./mongodb-backup-restore-util --https --host <targetHost> \
     --port <targetPort> \
     --opStart <opLogStartTimeStamp> \
     --opEnd <opLogEndTimeStamp> \
     --logFile <logPath> \
     --oplogSourceAddr <oplogSourceAddr> \
     --apiKey <apiKey> \
     --groupId <groupId> \
     --rsId <rsId> \
     --whitelist <database1.collection1, database2, etc.> \
     --blacklist <database1.collection1, database2, etc.> \
     --seedReplSetMember \
     --oplogSizeMB <size> \
     --seedTargetPort <port> \
     --ssl \
     --sslCAFile <path> \
     --sslPEMKeyFile <path>
   

   The mongodb-backup-restore-util command uses the following options:

   Option	Required	Description
   --https	Optional	Use if you need TLS/SSL to connect to the --oplogSourceAddr.
   --host	Required	Provide the hostname or IP address for the host that serves the mongod to which the oplog should be applied.
   --port	Required	Provide the port for the host that serves the mongod to which the oplog should be applied.
   --opStart	Required	Provide the BSON timestamp for the first oplog entry you want to include in the restore.
   --opEnd	Required	Provide the BSON timestamp for the last oplog entry you want to include in the restore.
   --logFile	Optional	Provide a path, including file name, where the MBRU log is written.
   --oplogSourceAddr	Required	Provide the URL to access the Ops Manager installation where the Oplog Store is configured.
   --apiKey	Required	Provide your Ops Manager Agent API Key.
   --groupId	Required	Provide the group ID.
   --rsId	Required	Provide the replica set ID.
   --whitelist	Optional	Provide a list of databases and/or collections to which you want to limit the restore.
   --blacklist	Optional	Provide a list of databases and/or collections to which you want to exclude from the restore.
   --seedReplSetMember	Optional	Use if you need a replica set member to re-create the oplog collection and seed it with the correct timestamp. Requires --oplogSizeMB and --seedTargetPort.
   --oplogSizeMB	Conditional	Provide the oplog size in MB. Required if --seedReplSetMember is set.
   --seedTargetPort	Conditional	Provide the port for the replica set’s primary. This may be different from the ephemeral port used. Required if --seedReplSetMember is set.
   --ssl	Optional	Use if you need TLS/SSL to apply oplogs to the mongod. Requires --sslCAFile and --sslPEMKeyFile.
   --sslCAFile	Conditional	Provide the path to the CA file. Required if --ssl is set.
   --sslPEMKeyFile	Conditional	Provide the path to the PEM certificate file. Required if --ssl is set.

4

Use the mongodump command to export a single database or collection from the temporary running mongod instance.

Specify the single database name using --db and, if needed, a --collection for a single collection.

The --out option specifies where the mongodump extracts the target database. Choose an empty directory the user executing mongodump can access.

copy

mongodump --port 27018 --db {single-database} \
  --out {new-database-path}

You can export only a single collection as well:

copy

mongodump --port 27018 --db {single-database} \
  --collection {collection-name} --out {new-database-path}

5

Use the mongorestore command to import the single database or collection.

Restore the single database to the desired instance using this mongorestore command:

copy

mongorestore --port 27017 --db {single-database} \
  {temp-database-path} --drop

If you are restoring a single collection, be sure to designate the collection:

copy

mongorestore --port 27017 --db {single-database} \
  --collection {collection-name} {temp-database-path} --drop

Any existing databases matching the name given for the --db option should be dropped using the --drop option. If you choose not to use the --drop option, the restore may produce errors for any documents with duplicate _id fields.

6

Shut down the temporary MongoDB instance and remove the temporary database.

1. Start the mongo shell.

   copy

   mongo {port}
   

2. Drop the database and shut down the mongod instance.

   copy

   admin = db.getSiblingDB("admin")
   admin.shutdownServer()
   exit
   

3. Delete the temporary database directory

   copy

   rm -rf {temp-database-path}
   

←   Query a Backup Snapshot Security  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.