Snapshot-based physical backups¶

Version added: 2.2.0

Considerations¶

Supported only for full backups
Available only if you run Percona Server for MongoDB in your environment as PBM uses the $backupCursor and $backupCursorExtended aggregation stages .

While a physical backup is a physical copy of your data directory, a snapshot is a point in time copy of your disk or a volume where the data files are stored. Restoring from snapshots is much faster and allows almost immediate access to data, however the database is unavailable during restore. Snapshot-based backups are especially useful for owners of large data sets with terabytes of data. Yet the snapshots don’t guarantee complete data consistency in sharded clusters.

This is where Percona Backup for MongoDB steps in. It provides the interface to make snapshot-based physical backups and restores and ensures data consistency. As a result, database owners benefit from increased performance and reduced downtime, and are sure that their data remains consistent.

The snapshot-based physical backup / restore flow consists of three distinct stages:

Preparing the database — done by PBM
Copying files — done by the user / client app
Completing the backup / restore — done by PBM.

This is the first stage of the snapshot-based backups where you can make them manually. Automated snapshot-based backups are planned for the future.

Make a backup¶

Refer to the Before you start section and make sure that you have made all the preparation steps for the backup.
To make a snapshot-based backup, run the pbm backup command with the type external:
```
$ pbm backup -t external 
```
When executing the command, PBM does the following:
- opens the $backupCursor
- prepares the database for file copy
- stores the backup metadata on the storage and adds it to the files to copy
- prints the prompt similar to the following:
```
Ready to copy data from:
<node-list>
```
You also see the backup name.
(Optional) You can check the backup progress with the pbm describe-backup. The command output provides the backup state and what nodes are running backup.
At this stage, you need to copy the dataDir contents of each node in the <node-list> to the storage / make a snapshot using the technology of your choice.
After the copy/snapshot is complete, run the following command to close the $backupCursor and finish the backup:
```
$ pbm backup-finish <backup_name>
```

Restore a backup¶

Before you start:¶

Shut down all mongos nodes. If you have set up any 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 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.

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: October 29, 2024
Created: October 29, 2024