Comprehensive Guide to Percona Backup for MongoDB: Architecture, Installation, Full and Incremental Backups, and Restoration

Overview – Percona Backup for MongoDB (PBM) is an open‑source, consistent backup tool for MongoDB replica sets and sharded clusters, supporting logical, physical, incremental, selective backup and restore, as well as point‑in‑time recovery (PITR). Physical backup features currently work only with Percona Server for MongoDB, so the guide focuses on logical backup for MongoDB Community 4.0+.

Architecture – PBM consists of pbm-agent processes running on every mongod instance (including secondaries and config servers) that monitor the PBM Control collections, acquire locks, and execute backup/restore operations. The PBM CLI interacts with agents via these collections, and several special collections (e.g., admin.pbmBackups, admin.pbmAgents, admin.pbmConfig, admin.pbmCmd, admin.pbmLock, admin.pbmLockOp, admin.pbmLog, admin.pbmOpLog, admin.pbmPITRChunks, admin.pbmPITRState, admin.pbmRestores, admin.pbmStatus) store configuration, state, and logs. Remote backup storage can be S3 or a filesystem, with backup files named by UTC start time.

Installation & Configuration

# wget https://downloads.percona.com/downloads/percona-backup-mongodb/percona-backup-mongodb-2.0.3/binary/tarball/percona-backup-mongodb-2.0.3-x86_64.tar.gz

# tar -xvf percona-backup-mongodb-2.0.3-x86_64.tar.gz

# echo "export PATH=$PATH:/usr/local/percona-backup-mongodb-2.0.3-x86_64" >> /etc/profile

# source /etc/profile

# create pbm role

shard1:PRIMARY> db.getSiblingDB("admin").createRole({"role":"pbmAnyAction","privileges":[{"resource":{"anyResource":true},"actions":["anyAction"]}],"roles":[]});

# create pbm user

shard1:PRIMARY> db.getSiblingDB("admin").createUser({user:"pbmuser","pwd":"secretpwd","roles":[{"db":"admin","role":"readWrite","collection":""},{"db":"admin","role":"backup"},{"db":"admin","role":"clusterMonitor"},{"db":"admin","role":"restore"},{"db":"admin","role":"pbmAnyAction"}]});

cat > /etc/pbm_config.yaml <
pbm config --file /etc/pbm_config.yaml --mongodb-uri "mongodb://pbmuser:[email protected]:27018,10.186.65.66:27018,10.186.65.68:27018/?replicaSet=config"
nohup pbm-agent --mongodb-uri "mongodb://pbmuser:[email protected]:27017" > /var/log/pbm-agent-27017.log 2>&1 &
# echo 'export PBM_MONGODB_URI="mongodb://pbmuser:[email protected]:27018,10.186.65.66:27018,10.186.65.68:27018/?replicaSet=config"' >> /etc/profile
# source /etc/profile
Full Backup
– Logical full backup is performed with:
pbm backup --type=logical --mongodb-uri "mongodb://pbmuser:[email protected]:27018,10.186.65.66:27018,10.186.65.68:27018/?replicaSet=config"
PBM supports compression (gzip, zstd, snappy, lz4) via the
--compression
flag and optional
--compression-level
. Backup priority can be set in the config file to influence which node runs the backup.
Backup Management
– Use
pbm status --mongodb-uri
to view agent health,
pbm list
to list snapshots,
pbm describe-backup
for details, and
pbm logs
with various filters (‑t, ‑e, ‑n, ‑s, ‑o, ‑i). Cancel a running backup with
pbm cancel-backup
and delete snapshots with
pbm delete-backup
(add
--force
to skip confirmation).
Incremental Backup (PITR)
– Enable point‑in‑time recovery:
pbm config --set pitr.enabled=true
Configure oplog chunk span and compression with
pitr.oplogSpanMin
and
pitr.compression
. PITR stores oplog chunks in the remote storage under the
pbmPitr
subdirectory.
Data Restoration
– Restore using
pbm restore --time="2023-02-22T08:30:00"
. For sharded clusters, stop the balancer, shut down mongos, optionally disable PITR, verify snapshots, then run the restore. After restoration, re‑enable PITR and the balancer.
Cross‑cluster restoration (different replica set names) is supported from v1.8 with the
--replset-remapping
option.
Performance Testing
– PBM includes
pbm-speed-test
to benchmark backup speed, e.g.:
pbm-speed-test storage --compression=gzip --size-gb 100
PBM’s performance is comparable to
mongodump
, but it offers consistent backups for sharded clusters, selective backup/restore, and point‑in‑time recovery.
Selective Backup and Restore
– Experimental feature allowing backup/restore of specific databases or collections using the
--ns
flag (e.g.,
pbm backup --ns=test.col1
or
pbm backup --ns=test.*
) and restoring with
pbm restore 2023-02-22T07:18:40Z --ns test.col1
. Time‑point restores require a full backup as a base.
Known Limitations
Only logical backup/restore is supported.
Sharded collections are not fully supported for selective backup.
Batch name specification is not supported.
Multi‑collection transactions are not supported.
System collections cannot be backed up/restored.
PITR requires a preceding full backup.
Reference:
Percona Backup for MongoDB Documentation