Backup with Percona Backup for MongoDB

Percona Backup for MongoDB (PBM) is an open-source distributed solution for consistent backup and restore of MongoDB clusters and replica sets. PBM supports physical, logical, incremental, and selective backups, as well as point-in-time recovery.

info

PBM is compatible with Percona Server for MongoDB and MongoDB Community/Enterprise Edition. Current version — 2.15.0 (June 2026).

Installation

Ubuntu / Debian

# Install percona-release
wget https://repo.percona.com/apt/percona-release_latest.$(lsb_release -sc)_all.deb
sudo dpkg -i percona-release_latest.$(lsb_release -sc)_all.deb

# Enable PBM repository
sudo percona-release enable -y pbm

# Install PBM
sudo apt update
sudo apt install -y percona-backup-mongodb

RHEL / CentOS / RED OS

# Install percona-release
sudo yum install -y https://repo.percona.com/yum/percona-release-latest.noarch.rpm

# Enable PBM repository
sudo percona-release enable -y pbm

# Install PBM
sudo yum install -y percona-backup-mongodb

After installation, the following tools are available:

Tool	Purpose
pbm	CLI for managing backups
pbm-agent	Agent that runs backup/restore on the MongoDB server
pbm-speed-test	Test compression and backup upload speed

info

Install pbm-agent on every server running mongod (except arbiters). pbm CLI can be installed on any computer with access to MongoDB.

Initial Setup

Step 1: Create PBM Role and User in MongoDB

Connect to the primary node of the replica set via mongosh and run:

// Connect to admin database: mongosh admin
// Create a role that allows any action on any resource
db.createRole({
  role: "pbmAnyAction",
  privileges: [{
    resource: { anyResource: true },
    actions: ["anyAction"]
  }],
  roles: []
})

// Create the PBM user
db.createUser({
  user: "pbmUser",
  pwd: "pbmPassword",
  roles: [
    { role: "readWrite", db: "admin" },
    { role: "backup", db: "admin" },
    { role: "clusterMonitor", db: "admin" },
    { role: "restore", db: "admin" },
    { role: "pbmAnyAction", db: "admin" }
  ]
})

Step 2: Start pbm-agent

Start pbm-agent on each replica set member:

systemctl enable pbm-agent
systemctl start pbm-agent
systemctl status pbm-agent

Step 3: Upload Storage Configuration

Create a YAML file with storage parameters and upload it via pbm config:

cat > /tmp/pbm_config.yaml << 'EOF'
storage:
  type: filesystem
  filesystem:
    path: /var/backups/pbm
EOF

pbm config --file /tmp/pbm_config.yaml

Local Filesystem

storage:
  type: filesystem
  filesystem:
    path: /var/backups/pbm

AWS S3 / S3-compatible

storage:
  type: s3
  s3:
    region: us-east-1
    bucket: my-pbm-backups
    credentials:
      access-key-id: AKIAIOSFODNN7EXAMPLE
      secret-access-key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

MinIO

storage:
  type: s3
  s3:
    region: us-east-1
    bucket: my-pbm-backups
    endpointUrl: https://minio.example.com
    credentials:
      access-key-id: minioadmin
      secret-access-key: minioadmin

Step 4: Verify Status

pbm status

Expected output:

Cluster:
========
rs0:
  - mongo-node:27017 [P]: pbm-agent [v2.15.0] OK

PITR incremental backup:
========================
Status [OFF]

Currently running:
==================
(none)

Backups:
========
Main storage:
  Type:       FS
  Path:       /var/backups/pbm
(no snapshots or PITR chunks)

Backup Types

PBM supports several backup types:

Type	Description	When to use
Physical	Copies data files at the filesystem level	Full backup, fast restore
Logical	Exports data via MongoDB API	Cross-version migration
Incremental	Copies only data changed since the previous backup in the chain	Save space, frequent backups
Selective	Backup specific databases or collections	Backup individual components

Physical Backup

A physical backup copies data files at the filesystem level. It is faster than logical but requires direct access to data files:

pbm backup --type physical

caution

Physical backup does not work in Docker containers (no access to WiredTiger journal files). Use logical backup for Docker deployments.

Logical Backup

Logical backup is the default type. It exports data via MongoDB API and works in any environment:

pbm backup

Incremental Backup

An incremental backup copies only data changed since the previous backup in the chain. The first incremental backup is created with the --base flag — it becomes the base for subsequent ones:

# First incremental backup (base for the chain)
pbm backup --type incremental --base

# Subsequent incremental backups
pbm backup --type incremental

caution

Incremental backup works at the WiredTiger file level and is not supported in Docker containers. Use logical backups for Docker deployments.

tip

Incremental backups significantly save space and time. Recommended schedule: full backup weekly + incremental daily.

Selective Backup

Backup a specific database:

pbm backup --ns "mydb.*"

Backup a specific collection:

pbm backup --ns "mydb.mycollection"

Point-in-Time Recovery

PBM supports restoring to a specific point in time using oplog chunks.

Enable PITR

pbm config --set 'pitr.enabled=true'

The pitr.oplogSpanMin parameter sets the interval for saving oplog chunks (in minutes, default 1):

pbm config --set 'pitr.oplogSpanMin=5'

caution

After a restore, PITR stops. To resume PITR, you need to create a new backup:

pbm backup --wait

Restore to a Specific Point in Time

pbm restore --time 2026-08-07T14:30:00 -y

Time format: YYYY-MM-DDTHH:MM:SS (no timezone suffix).

Backup Management

List Backups

pbm list

Backup Details

pbm describe-backup backup-2026-08-07

Delete Backup

pbm delete-backup backup-2026-08-07 -y

Cancel Backup

pbm cancel-backup

Restore

Restore from Backup

pbm restore backup-2026-08-07 -y --wait

info

Logical restore runs on a running cluster. Physical restore requires mongod to be stopped.

Selective Restore

Restore a specific database:

pbm restore backup-2026-08-07 --ns "mydb.*" -y

Restore a specific collection:

pbm restore backup-2026-08-07 --ns "mydb.mycollection" -y

Collection Cloning during Restore

Create a copy of a collection with a different name:

pbm restore backup-2026-08-07 --ns-from "mydb.source" --ns-to "mydb.clone" -y

Backup Compression

Enable compression to save space:

pbm config --set 'backup.compression=gzip'

Available algorithms: gzip, snappy, lz4, s2, pgzip, zstd.

info

Backups of encrypted data are stored in encrypted form. The encryption key must be available on the server during restore. For details on encryption, see Data Encryption in Percona Server for MongoDB.