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 <<EOF
storage:
  type: filesystem
  filesystem:
    path: /data/backup
EOF

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