Query a Backup Snapshot
On this page
- OAuth 2.0 authentication for programmatic access to Cloud Manager is available as a Preview feature.
- The feature and the corresponding documentation might change at any time during the Preview period. To use OAuth 2.0 authentication, create a service account to use in your requests to the Cloud Manager Public API.
Cloud Manager provides queryable backups. This functionality allows you to more quickly query specific backup snapsnots. You can use the queryable backups to:
Restore a subset of data within the MongoDB deployment.
Compare previous versions of data against the current data.
Identify the best point in time to restore a system by comparing data from multiple snapshots.
Considerations
Read-Only Instance
Cloud Manager provisions these queryable snapshots as read-only MongoDB instances.
Important
These instances are available for up to 24 hours.
Query Restrictions on the Queryable Snapshots
You cannot perform the following operations on queryable snapshots:
Queries that require disk usage, such as running aggregation with the
allowDiskUse
option to perform large sort operations.
Cannot Query Encrypted Snapshots
If you encrypted your snapshots, you can't query those encrypted snapshots.
Cannot Query Namespace Filtered Snapshots
If you applied namespace filters to a snapshot, you can't query that snapshot.
Connection Methods
Connections to these instances are over TLS/SSL and require x.509 authentication. Cloud Manager provides:
An executable that creates a tunnel which handles the connection, including the client TLS/SSL and the x.509 authentication.
x.509 certificates if you want to handle the connection details manually, including the TLS/SSL and the x.509 authentication.
Prerequisites
Queryable backups are available for MongoDB 3.2 or later replica sets or MongoDB 3.2 or later sharded clusters with CSRS.
Important
Use the latest versions of MongoDB Database Tools, which include
mongodump
and mongorestore
.
Use the latest version of mongosh
.
Older versions of mongodump
include an issue
that can cause keys in collection options to be dumped in the wrong order.
To learn more, see TOOLS-3411.
Query Backup (Use Tunnel to Connect)
Note
The tunnel handles the security (TLS/SSL and x.509 authentication) for connecting to the instance.
Follow the prompts to query a backup snapshot.
Select the snapshot to query and click Next.
Start the process to query a snapshot. You will be prompted for 2-factor verification.
Select Backup Tunnel as the connection method to the queryable snapshot.
Select your Platform and download.
Uncompress the downloaded file.
Note
Wait for the Queryable Snapshot to mount before you continue. Snapshot mount time depends on the size of the snapshot. To verify the snapshot is mounted:
In MongoDB Cloud Manager, go to the Continuous Backup page for your project.
If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Click Continuous Backup in the sidebar.
The Continuous Backup page displays.
Select the Restore History tab.
When the snapshot is mounted, the Status column reports the date and time of the mount operation.
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.
For the full list of options you can pass to the tunnel, run the tunnel exectuable with the
-h
option:./<tunnel executable> -h Use
mongosh
or a MongoDB driver to connect to the backup via the tunnel.If connecting locally from the same machine as where the tunnel is running, you do not need to specify a connection string or host information. Otherwise, specify a connection string or host information for the machine where the tunnel is running.
If you have changed the port that the tunnel is listening on, you must specify the port information when connecting.
Tip
Once you have finished querying this snapshot, you can terminate the queryable instance:
Go to the Restore History and hover over the Status column for the deployment item.
Click Cancel.
Important
Rotate Master Key after Restoring Snapshots Encrypted with AES256-GCM
If you restore an encrypted snapshot that Cloud Manager encrypted with AES256-GCM, rotate your master key after completing the restore.
Query Backup (Handle TLS Authentication Manually)
Note
The X.509 certificates are valid for 24 hours.
Follow the prompts to query a backup snapshot.
Select the snapshot to query and click Next.
Start the process to query a snapshot. If prompted for your password, enter your password to verify.
Select Connect Manually as the connection method to the queryable snapshot.
Download the X.509 client PEM file.
Download the Certificate Authority PEM file.
Note
Wait for the Queryable Snapshot to mount before you continue. Snapshot mount time depends on the size of the snapshot. To verify the snapshot is mounted:
In MongoDB Cloud Manager, go to the Continuous Backup page for your project.
If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Click Continuous Backup in the sidebar.
The Continuous Backup page displays.
Select the Restore History tab.
When the snapshot is mounted, the Status column reports the date and time of the mount operation.
Use
mongosh
or a MongoDB driver to connect to the queryable backup host. To connect, you must specify the hostname and port, the TLS option, and the X.509 certificates.Example
If using
mongosh
to connect to the instance:mongosh my-queryable-backup-host.mongodb.com:27217 \ --tls --tlsCertificateKeyFile <client certificate> \ --tlsCAFile mms-backup-ca.pem
Tip
Once you have finished querying this snapshot, you can terminate the queryable instance:
Go to the Restore History and hover over the Status column for the deployment item.
Click Cancel.
Important
Rotate Master Key after Restoring Snapshots Encrypted with AES256-GCM
If you restore an encrypted snapshot that Cloud Manager encrypted with AES256-GCM, rotate your master key after completing the restore.
Next Steps
To restore a database or a collection using the queryable backup MongoDB instance, see Restore a Database or Collection from Queryable Backup.