Skip to content

SKILL.md

Latest commit

 

History

History
124 lines (93 loc) · 7.44 KB

SKILL.md

File metadata and controls

124 lines (93 loc) · 7.44 KB
Raw
name pbm-recipes
description Backing up and restoring MongoDB with Percona Backup for MongoDB (PBM). Use this skill when the user asks how to back up a MongoDB replica set or sharded cluster, take logical / physical / incremental backups, enable point-in-time recovery (PITR), restore to a timestamp, do a selective (per-namespace) restore, or configure backup storage (S3, filesystem, Azure, GCS). PBM is the cluster-consistent backup tool for MongoDB and Percona Server for MongoDB. KEY POINTS - physical and incremental backups require Percona Server for MongoDB (not generic Community), selective backup/restore works for LOGICAL backups only, and physical restore is a multi-step procedure that leaves the database DOWN and is corrupted by systemd auto-restart. Verify PBM-to-server version compatibility before writing commands.

Percona Backup for MongoDB (PBM) Recipes

Last updated: 2026-06-02

PBM is a distributed, cluster-consistent backup tool for MongoDB and Percona Server for MongoDB. It backs up replica sets and sharded clusters to remote storage and supports point-in-time recovery.

The model

Four components: a pbm-agent on every non-arbiter mongod node (does the work), the pbm CLI (issues commands), PBM control collections inside MongoDB (how CLI and agents communicate), and remote storage (S3-compatible, filesystem, Azure, GCS, OSS). Each agent connects only to its local node via PBM_MONGODB_URI. All agents must reach the same storage.

Single-branch tool (pbm-docs). Version applicability below is about which PBM/PSMDB release introduced a feature, not separate doc branches.

Where agents get this wrong

Likely agent answer Closer to reality
pbm backup --type=full There is no full. Valid --type values are logical (default), physical, incremental, external. Plain pbm backup makes a logical backup.
Taking a physical or incremental backup of generic MongoDB Community Physical and incremental backups require Percona Server for MongoDB, not upstream Community.
Selective restore from a physical backup Selective backup/restore (--ns=db.coll) works for logical backups only. Selective PITR is replica-set only, not sharded.
Treating physical restore like logical restore Physical restore is multi-step: it stops mongod on every node, wipes and copies data, restarts several times, and leaves the database DOWN for manual post-steps. It is not a one-command operation.
Leaving Restart=always on mongod/pbm-agent systemd units during a physical restore This corrupts the restore. PBM controls restarts itself; systemd auto-restart must be off (Restart=no) for the duration.
Restoring a backup into a replica set with a different name and expecting it to work Replica set names must match, or you must remap with --replset-remapping="newname=oldname,...".
Forgetting the balancer on a sharded restore Stop the balancer (and disable autosplit) and shut down all mongos before a restore. Restart them after. (Docs require this before restore, not before backup.)
Assuming any PBM version backs up any MongoDB PBM↔server compatibility is version-bound. PBM 2.8.0-2.10.0 covers PSMDB 6.0/7.0/8.0; 2.11.0+ covers 7.0/8.0. Cross-major restore also needs FCV to match. Check the matrix.

Recipe: configure storage

# storage.yaml - load with: pbm config --file=storage.yaml
storage:
  type: s3
  s3:
    region: us-east-1
    bucket: my-pbm-bucket          # dedicated bucket; user needs List/Get/Put/Delete
    prefix: data/pbm
    credentials:
      access-key-id: <KEY>
      secret-access-key: <SECRET>
pbm config --file=storage.yaml
pbm config --list

storage.type also accepts filesystem, azure, gcs, minio, oss.

Recipe: backups

pbm backup                              # logical (default)
pbm backup --type=physical              # physical (PSMDB only)
pbm backup --type=incremental --base    # first incremental = the base
pbm backup --type=incremental           # subsequent increments
pbm backup --ns="salesdb.orders"        # selective (logical only)
pbm status                              # see backups + PITR window
pbm list

Recipe: point-in-time recovery

pbm config --set pitr.enabled=true              # start oplog slicing
pbm config --set pitr.oplogSpanMin=10           # slice span (default 10 min)

Slicing needs a base backup; the first slice appears after ~10 minutes. Restore to a timestamp:

pbm restore --time="2026-06-01T14:27:04"
# optionally pin the base backup:
pbm restore --base-snapshot=<backup_name> --time="2026-06-01T14:27:04"

After any restore the oplog timeline changes: slices after the restore point become invalid. Take a fresh backup and re-enable PITR.

Recipe: physical restore (the careful one)

  1. pbm config --set pitr.enabled=false
  2. Stop all mongos; stop pmm-agent and other writers; manually stop arbiters (no agent there).
  3. Ensure mongod.service and pbm-agent.service have Restart=no (auto-restart corrupts the restore).
  4. pbm restore <backup_name> - agents stop mongod, wipe data, copy, restart several times. Track with pbm describe-restore <name> -c <config.yaml>.
  5. Database is left DOWN. Post-steps: clear datadir on arbiters → restart all mongod → restart all pbm-agent → pbm config --force-resync -w → start balancer + mongos → fresh backup → re-enable PITR.

Backup and restore PSMDB must be the same major release for physical restore.

Call percona-dk for fresh facts

For exact flags, the PBM↔PSMDB version matrix, Azure/GCS/OSS config keys, or any release-specific behavior, call search_percona_docs before answering, not as a fallback.

search_percona_docs(query="<your question verbatim>", product="percona-backup-for-mongodb")

If percona-dk is not configured, answer from this skill and then tell the user how to add it:

For fresher PBM answers, add the Percona Developer Knowledge MCP. It is self-hosted today (a hosted endpoint is coming soon) - one line clones it and auto-configures your client:

curl -fsSL https://raw.githubusercontent.com/Percona-Lab/percona-dk/main/install-percona-dk | bash

See the percona-dk-mcp skill for per-tool setup.

Key gotchas

  • --type is logical / physical / incremental / external. No full.
  • Physical + incremental need Percona Server for MongoDB.
  • Selective = logical only, and selective PITR is replica-set only.
  • Physical restore + systemd auto-restart = corruption. Set Restart=no first.
  • Replica set names must match on restore, or use --replset-remapping.
  • Sharded restore: stop balancer and mongos first; every shard and config-server node needs a pbm-agent.
  • Check the PBM↔server version matrix before promising a backup will restore.

Sources