Restore from a physical backup¶

To restore a backup, use the pbm restore command supplying the backup name from which you intend to restore. Percona Backup for MongoDB identifies the type of the backup (physical, logical or incremental) and restores the database up to the restore_to_time timestamp (available in pbm list output starting with version 1.4.0).

Considerations¶

Disable point-in-time recovery. A restore and point-in-time recovery oplog slicing are incompatible operations and cannot be run simultaneously.
```
$ pbm config --set pitr.enabled=false
```
The Percona Server for MongoDB version for both backup and restore data must be within the same major release.
Make sure all nodes in the cluster are healthy (i.e. either PRIMARY or SECONDARY). Each pbm-agent needs to be able to connect to its local node and run queries in order to perform the restore.
For PBM versions before 2.1.0, physical restores are not supported for deployments with arbiter nodes.

Before you start¶

Shut down all mongos nodes as the database won’t be available while the restore is in progress.
Shut down all pmm-agent and other clients that can do the write operations to the database. This is required to ensure data consistency after the restore.
Stop the arbiter nodes manually since there’s no pbm-agent on these nodes to do that automatically.

Restore a database¶

List the backups
```
$ pbm list
```
Make a restore
```
$ pbm restore <backup_name>
```
During the physical restore, pbm-agent processes stop the mongod nodes, clean up the data directory and copy the data from the storage onto every node. During this process, the database is restarted several times.

You can track the restore progress using the pbm describe-restore command. Don’t run any other commands since they may interrupt the restore flow and cause the issues with the database.

Post-restore steps¶

After the restore is complete, do the following:

Restart all mongod nodes.
Note

You may see the following message in the mongod logs after the cluster restart:
```
"s":"I",  "c":"CONTROL",  "id":20712,   "ctx":"LogicalSessionCacheReap","msg":"Sessions collection is not set up; waiting until next sessions reap interval","attr":{"error":"NamespaceNotFound: config.system.sessions does not exist"}}}}
```
This is expected behavior of periodic checks upon the database start. During the restore, the config.system.sessions collection is dropped but Percona Server for MongoDB recreates it eventually. It is a normal procedure. No action is required from your end.
Restart all pbm-agents
Run the following command to resync the backup list with the storage:
```
$ pbm config --force-resync
```
Start the balancer and start mongos nodes.
We recommend to make a fresh backup to serve as the new base for future restores.
Enable point-in-time recovery if required.

Define a `mongod` binary location¶

Version added: 2.0.4

During physical restores, Percona Backup for MongoDB performs several restarts of the database. By default, it uses the location of the mongod binaries from the $PATH variable to access the database. If you have defined the custom path to the mongod binaries, make Percona Backup for MongoDB aware of it by specifying this path in the configuration file:

restore:
    mongodLocation: /path/to/mongod

If you have different paths to mongod binaries on every node of your cluster / replica set, use the mongodLocationMap option to specify your custom paths for each node.

restore:
    mongodLocationMap:
       "node01:27017": /path/to/mongod
       "node03:27017": /another/path/to/mongod

Parallel data download¶

Version added: 2.1.0

Percona Backup for MongoDB downloads data chunks from the S3 storage concurrently during physical restore. Read more about benchmarking results in the Speeding up MongoDB restores in PBM blog post by Andrew Pogrebnoi.

Here’s how it works:

During the physical restore, Percona Backup for MongoDB starts the workers. The number of workers equals to the number of CPU cores by default. Each worker has a memory buffer allocated for it. The buffer is split into spans for the size of the data chunk. The worker acquires the span to download a data chunk and stores it into the buffer. When the buffer is full, the worker waits for the free span to continue the download.

You can fine-tune the parallel download depending on your hardware resources and database load. Edit the PBM configuration file and specify the following settings:

restore:
   numDownloadWorkers: <int>
   maxDownloadBufferMb: <int>
   downloadChunkMb: 32

numDownloadWorkers - the number of workers to download data from the storage. By default, it equals to the number of CPU cores
maxDownloadBufferMb - the maximum size of memory buffer to store the downloaded data chunks for decompression and ordering. It is calculated as numDownloadWorkers * downloadChunkMb * 16
downloadChunkMb is the size of the data chunk to download (by default, 32 MB)

Selective Incremental

List the backups
```
$ pbm list
```

Run the pbm restore command in the format:

$ pbm restore <backup_name> --ns <database.collection>

You can specify several namespaces as a comma-separated list for the --ns flag: <db1.col1>, <db2.*>.

During the restore, Percona Backup for MongoDB retrieves the file for the specified database / collection and restores it.

Restore with users and roles¶

To restore a custom database with users and roles from a full backup, add the --with-users-and-roles flag to the pbm restore command:

$ pbm restore <backup_name> --ns <database.*> --with-users-and-roles

Restore flow from an incremental backup is the same as the restore from a full physical backup: specify the backup name for the pbm restore command:

$ pbm restore 2022-11-25T14:13:43Z

Percona Backup for MongoDB recognizes the backup type, finds the base incremental backup, restores the data from it and then restores the modified data from applicable incremental backups.

After the restore is complete, do the following:

Restart all mongod nodes and pbm-agents.
Note

You may see the following message in the mongod logs after the cluster restart:
```
"s":"I",  "c":"CONTROL",  "id":20712,   "ctx":"LogicalSessionCacheReap","msg":"Sessions collection is not set up; waiting until next sessions reap interval","attr":{"error":"NamespaceNotFound: config.system.sessions does not exist"}}}}
```
This is expected behavior of periodic checks upon the database start. During the restore, the config.system.sessions collection is dropped but Percona Server for MongoDB recreates it eventually. It is a normal procedure. No action is required from your end.
Resync the backup list from the storage.
Start the balancer and the mongos node.
As the general recommendation, make a new base backup to renew the starting point for subsequent incremental backups.

Next steps¶

Point-in-time recovery

Useful links¶

View restore progress

Get expert help¶

If you need assistance, visit the community forum for comprehensive and free database knowledge, or contact our Percona Database Experts for professional support and services.

Community Forum Get a Percona Expert

Last update: November 1, 2024
Created: November 1, 2024