Restore a 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¶
-
While the restore is running, prevent clients from accessing the database. The data will naturally be incomplete while the restore is in progress, and writes the clients make cause the final restored data to differ from the backed-up data.
-
Backups made with Percona Backup for MongoDB prior to v1.5.0 are incompatible for restore with Percona Backup for MongoDB v1.5.0 and later. This is because processing of system collections
Users
andRoles
has changed: in v1.5.0,Users
andRoles
are copied to temporary collection during backup and must be present in the backup during restore. In earlier versions of Percona Backup for MongoDB,Users
andRoles
are copied to a temporary collection during restore. Therefore, restoring from these backups with Percona Backup for MongoDB v1.5.0 isn’t possible.The recommended approach is to make a fresh backup after upgrading Percona Backup for MongoDB to version 1.5.0.
-
For versions earlier than 1.x, Percona Backup for MongoDB performs a full all-databases, all collections restore and does not offer an option to restore only a subset of collections in the backup, as MongoDB’s
mongodump
tool does. -
Starting with versions 1.x, Percona Backup for MongoDB replicates
mongodump’s
behavior to only drop collections in the backup. It does not drop collections that are created new after the time of the backup and before the restore. Run adb.dropDatabase()
manually in all non-system databases (these are all databases except “local”, “config” and “admin”) before runningpbm restore
if you want to guarantee that the post-restore database only includes collections that are in the backup.
- 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.
- The Percona Server for MongoDB version for both backup and restore data must be within the same major release.
- Incremental backups made with PBM before PBM 2.1.0 are incompatible for restore with PBM 2.1.0 and onwards.
- Physical restores are not supported for deployments with arbiter nodes.
- Supported only for full physical backups
- Available only if you run Percona Server for MongoDB in your environment as PBM uses the
$backupCursor and $backupCursorExtended aggregation stages
.
Before you start¶
-
Stop the balancer and disable chunks autosplit. To verify that both are disabled, run the following command:
> sh.status()
You should see the following output
autosplit: Currently enabled: no balancer: Currently enabled: no Currently running: no
-
Shut down all
mongos
nodes to stop clients from accessing the database while restore is in progress. This ensures that the final restored data doesn’t differ from the backed-up data. -
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. -
For PBM version 2.3.1 and earlier, manually disable point-in-time recovery if it is enabled.
$ pbm config --set pitr.enabled=false
To learn more about point-in-time recovery, see Point-in-time recovery.
- 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. -
For PBM version 2.3.1 and earlier, manually disable point-in-time recovery if it is enabled.
$ pbm config --set pitr.enabled=false
To learn more about point-in-time recovery, see Point-in-time recovery.
You can restore a specific database or a collection either from a full or a selective backup. Read about known limitations of selective restores.
Before you start, shut down all mongos
nodes, pmm-agent
processes and clients that can do writes to the database as it won’t be available while the restore is in progress.
- 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¶
-
List the backups to restore from
$ pbm list
-
Restore from a desired backup. Replace the
<backup_name>
with the desired backup in the following command:$ pbm restore <backup_name>
Note that you can restore a sharded backup only into a sharded environment. It can be your existing cluster or a new one. To learn how to restore a backup into a new environment, see Restoring a backup into a new environment.
Post-restore steps
After a cluster’s restore is complete, do the following:
- Start the balancer and all
mongos
nodes to reload the sharding metadata. - We recommend to make a fresh backup to serve as the new base for future restores.
- Enable point-in-time recovery if required.
Adjust memory consumption¶
Percona Backup for MongoDB config includes the restore options to adjust the memory consumption by the pbm-agent
in environments with tight memory bounds. This allows preventing out of memory errors during the restore operation.
restore:
batchSize: 500
numInsertionWorkers: 10
The default values were adjusted to fit the setups with the memory allocation of 1GB and less for the agent.
Starting with version 2.8.0, you can override the number of insertion workers for a specific restore operation.
$ pbm restore <backup_name> --numInsertionWorkers 15
Increasing the number may increase the restore speed. However, increase the number of workers with caution, not to run into higher than expected disk and CPU usage.
Restore from a logical backup made on previous major version of Percona Server for MongoDB¶
In some cases you may need to restore from a backup made on previous major version of Percona Server for MongoDB. To make this happen, Feature Compatibility Version (FCV) values in both backup and the destination environment must match.
Starting with version 2.1.0, Percona Backup for MongoDB stores the FCV value in the backup metadata. If it doesn’t match the FCV value on the destination environment, you see the warning in the pbm status
output so that you can manually adjust it before the restore.
2023-04-10T10:48:54Z 302.80KB <logical> [ERROR: backup FCV "6.0" is incompatible with the running mongo FCV "5.0"] [2023-04-10T10:49:14Z]
2023-04-10T08:40:10Z 172.25KB <logical> [ERROR: backup mongo version "6.0.5-4" is incompatible with the running mongo version "5.0.15-13"] [2023-04-10T08:40:28Z]
The following example illustrates the restore from a backup made on Percona Server for MongoDB 4.4 on Percona Server for MongoDB 5.0.
-
Check the FCV value for the backup
$ pbm status
Sample output:
Snapshots: 2023-04-10T10:51:28Z 530.73KB <logical> [ERROR: backup FCV "4.4" is incompatible with the running mongo FCV "5.0"] [2023-04-10T10:51:44Z]
-
Set the Feature Compatibility Version value to 4.4
> db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } )
-
Restore the database
$ pbm restore 2023-04-10T10:51:28Z
-
Set the Feature Compatibility Version value to 5.0
> db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )
-
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:
- Remove the contents of the datadir on any arbiter nodes
-
Restart all
mongod
nodesNote
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 coresmaxDownloadBufferMb
- the maximum size of memory buffer to store the downloaded data chunks for decompression and ordering. It is calculated asnumDownloadWorkers * downloadChunkMb * 16
downloadChunkMb
is the size of the data chunk to download (by default, 32 MB)
-
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.*>
. For example, --ns=customers.payments,invoices.*
.
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 a collection under a different name¶
You can restore a specific collection under a different name alongside the current collection. This is useful when you troubleshoot database issues and need to compare the data in both collections to identify the root of the issue.
Note that in version 2.8.0 you can restore a single collection and this collection must be unsharded.
To restore a collection, pass the collection name from the backup for the --ns-from
flag and the new name for the --ns-to
flag:
$ pbm restore <backup_name> --ns-from <database.collection> --ns-to <database.collection_new>
The new collection has the same data and indexes as the source collection. You must provide a unique name for the collection you restore, otherwise the restore fails.
You can restore a collection under a new name up to the specified time. Instead of the backup name, specify the timestamp, the source collection name and the new name as follows:
$ pbm restore --time=<timestamp> --ns-from <database.collection> --ns-to <database.collection_new>
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 andpbm-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.
Restoring a backup into a new environment¶
To restore a backup from one environment to another, ensure the following:
-
Percona Backup for MongoDB configuration in the new environment must point to the same remote storage that is defined for the original environment, including the authentication credentials if it is an object store. Once you run
pbm list
and see the backups made from the original environment, then you can run thepbm restore
command. -
Don’t run
pbm backup
from the new environment while Percona Backup for MongoDB configuration is pointing to the remote storage location of the original environment.
Restoring into a cluster / replica set with a different name¶
Starting with version 1.8.0, you can restore logical backups into a new environment that has the same or more number of shards and these shards have different replica set names. Starting with version 2.2.0, you can restore environments that have custom shard names.
Starting with version 2.2.0, you can restore physical and incremental physical backups into a new environment with a different replica set names. Note that the number of shards must be the same as in the environment where the you made the backup.
To restore data to the environment with different replica set names, configure the name mapping between the source and target environments. You can either set the PBM_REPLSET_REMAPPING
environment variable for pbm
CLI or use the --replset-remapping
flag for PBM commands. The mapping format is <rsTarget>=<rsSource>
.
Important
Configure replica set name mapping for all shards in your cluster. Otherwise, Percona Backup for MongoDB attempts to restore the unspecified shard to the target shard with the same name. If there is no shard with such name or it is already mapped to another source shard, the restore fails.
Configure the replica set name mapping:
$ export PBM_REPLSET_REMAPPING="rsX=rsA,rsY=rsB"
$ pbm restore <timestamp> --replset-remapping="rsX=rsA,rsY=rsB"
The --replset-remapping
flag is available for the following commands: pbm restore
, pbm list
, pbm status
, pbm oplog-replay
.
Note
Follow the post-restore steps on the new environment after the restore is complete.
This ability to restore data to clusters with different replica set names and the number of shards extends the set of environments compatible for the restore.
Next steps¶
Useful links¶
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.
Created: January 23, 2025