Navigation

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 Cloud 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:

    ./<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.

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:

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.

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

For 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:

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.

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

For example, to restore from the /mydata/restoredata/test directory to a new database restoredTest:

mongorestore --port 27017 --db restoredTest /mydata/restoredata/test --drop

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

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.

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

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

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

Secure Copy (SCP) Delivery

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). Cloud 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
    Group Select a group 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.

    Cloud 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 Cloud Manager send you a copy 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, Cloud Manager prompts you for your 2FA code. Enter your 2FA code, then click Finalize Request.

2

Retrieve the snapshot.

Cloud Manager creates a link to the snapshot. 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.

Important

Skip to Restore the Database.

Send Snapshot using SCP

Direct Cloud 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 Cloud 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, Cloud Manager prompts you for your 2FA code. Enter your 2FA code, then click Finalize Request.

2

Retrieve the snapshot.

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.

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

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

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.

    ./mongodb-backup-restore-util --https --host {targetHost} \
      --port {targetPort} \
      --opStart {opLogStartTimeStamp} \
      --opEnd {opLogEndTimeStamp} \
      --logFile pitLog.log \
      --oplogSourceAddr api-backup-dev.mongodb.com \
      --apiKey {apiKey}
    

    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 mongod to which the oplog should be applied.
    --port Required Provide the port for the host that serves mongod to which the oplog should be applied.
    --opStart Required Provide the timestamp for the first Oplog entry you want to include in the restore.
    --opEnd Required Provide the timestamp for the last Oplog entry you want to include in the restore.
    --logFile Required Provide a path, including file name, where the log is written.
    --oplogSourceAddr Required Provide the URL for the Oplog. This is api-backup-dev.mongodb.com for Cloud Manager.
    --apiKey Required Provide your Cloud Manager Agent API Key.
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.

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

You can export only a single collection as well:

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:

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

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

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.

    mongo {port}
    
  2. Drop the database and shut down the mongod instance.

    admin = db.getSiblingDB("admin")
    admin.shutdownServer()
    exit
    
  3. Delete the temporary database directory

    rm -rf {temp-database-path}