Restore from a snapshot-based 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¶

Shut down all mongos nodes. If you have set up the automatic restart of the database, disable it.
Stop the arbiter nodes manually since there’s no pbm-agent on these nodes to do that automatically.

Restore a database¶

Restore from a backup made through PBM¶

The following procedure describes the restore process from backups made through PBM. It is also possible to attempt restoring from snapshots made without PBM (this feature is experimental). See Restore from a backup made outside PBM.

To perform a restore, run the following command:

$ pbm restore --external

Percona Backup for MongoDB stops the database, cleans up data directories on all nodes, provides the restore name and prompts you to copy the data:

Starting restore <restore_name> from '[external]'.................................................................................................................................Ready to copy data to the nodes data directory.
    After the copy is done, run: pbm restore-finish <restore_name> -c </path/to/pbm.conf.yaml>
    Check restore status with: pbm describe-restore <restore_name> -c </path/to/pbm.conf.yaml>
    No other pbm command is available while the restore is running!

Copy the data back. While a backup is made from a single node of a replica set, for the restore you must copy the data to every node of the corresponding replica set in the cluster. For example, given a backup of a 3-node replica set rs1 where backup was taken from node3, copy back the data to all 3 nodes in rs1.
After you copied the files to the nodes, complete the restore with the following command:
```
$ pbm restore-finish <restore_name> -c </path/to/pbm-conf.yaml>
```
At this stage, Percona Backup for MongoDB reads the metadata from the backup, prepares the data for the cluster / replica set start and ensures its consistency. The database is restored to the timestamp specified in the restore_to_time of the metadata.
Note

If you use a filesystem as the remote backup storage, both pbm-agent and pbm CLI must have the same permissions to it. To achieve this, run the pbm restore-finish command as the mongod user:
```
$ sudo -u mongod -s pbm restore-finish <restore_name> -c </path/to/pbm-conf.yaml> --mongodb-uri=MONGODB_URI
```
Optional. You can track the restore progress by running the pbm describe-restore command.

Post-restore steps¶

After the restore is complete, do the following:

Start all mongod nodes
Start 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.
Make a fresh backup to serve as the new base for future restores.

Restore from a backup made outside PBM¶

Warning

This feature is experimental.

Important

For external backups made through PBM, PBM performs compatibility checks for the backup and the target cluster. If you restore a backup made without PBM, it cannot ensure that the backup was made properly and in a consistent manner. Therefore, the backup compatibility is your responsibility.

To restore an external backup made without PBM, you need to specify the following for the pbm restore command:

a path to the configuration file of the mongod node on the source cluster from where the backup was made. This is the configuration file that PBM will use during the restore. It should contain the storage options per replica set name, for example:

rs1:
    storage:
        directoryPerDB: true
rs2:
    storage:
        directoryPerDB: true

To restore data that was encrypted at rest, make sure data-at-rest encryption settings on the source and target clusters are the same.

a timestamp to restore to

To restore from a backup, do the following:

Start a restore
```
$ pbm restore --external -c </path/to/mongod.conf> --ts 
```
If the path to the source cluster mongod.conf is undefined, PBM tries to retrieve the required configuration options from the mongod.conf of the target cluster.

If the timestamp to restore to is undefined, PBM looks into the actual data during the restore and defines the most recent common cluster time across all shards. PBM restores the database up to this time.
Next, copy the data files. Note that you must copy the data to every data-bearing node of your cluster / replica set.
Complete the restore by running:
```
$ pbm restore-finish <restore_name> -c </path/to/pbm.conf.yaml>
```
At this stage, Percona Backup for MongoDB prepares the data for the cluster / replica set start and ensures its consistency.
Note

If you use a filesystem as the remote backup storage, both pbm-agent and pbm CLI must have the same permissions to it. To achieve this, run the pbm restore-finish command as the mongod user:
```
$ sudo -u mongod -s pbm restore-finish <restore_name> -c </path/to/pbm-conf.yaml> --mongodb-uri=MONGODB_URI
```
Don’t forget to complete the post-restore steps.

Useful links¶

View restore progress

Last update: April 16, 2025
Created: April 16, 2025