backup

name	backup
summary	Backup and restore Couchbase clusters using cbbackupmgr — configure backup repositories, run incremental backups, merge, restore, and back up to cloud object storage (S3, GCS, Azure)
description	Backup and restore Couchbase clusters using cbbackupmgr — configure backup repositories, run incremental backups, merge, restore, and back up to cloud object storage (S3, GCS, Azure)
allowed-tools	Bash
compatibility	Requires cbbackupmgr installed (included with Couchbase Server). Cloud backup requires Server 6.6+.
metadata	{"last_verified":"2026-05","min_server_version":"6.0","handoff":[{"condition":"user asks about disaster recovery planning or RTO/RPO","skill":"disaster-recovery"},{"condition":"user asks about RBAC roles for backup","skill":"security"}]}

Couchbase Backup and Restore

cbbackupmgr is the primary tool for backing up and restoring Couchbase clusters. It uses incremental backups by default, minimizing transfer time and storage.

Hardware minimum: 4 CPU cores, 8 GiB RAM. Recommended: 16 cores, 16 GiB RAM, SSD.

---

Core Concepts

Archive: top-level directory containing one or more backup repositories and a logs/ folder.

Repository: a directory inside the archive that holds the backup configuration and all backup snapshots for a specific cluster. Typically one repository per cluster.

Backup snapshot: a timestamped folder inside the repository created by each backup run. Incremental — only data changed since the last snapshot is stored.

/backup-archive/                  ← archive
  logs/
  my-cluster-repo/                ← repository
    backup-config.json
    2024-06-01T00:00:00Z/         ← snapshot (full or incremental)
    2024-06-02T00:00:00Z/
    2024-06-03T00:00:00Z/

---

Step 1 — Configure a Repository

Create the repository before running any backups. This writes the backup configuration.

cbbackupmgr config \
  --archive /backup-archive \
  --repo my-cluster-repo

To include only specific buckets:

cbbackupmgr config \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --include-data travel-sample,myapp

---

Step 2 — Run a Backup

cbbackupmgr backup \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --cluster couchbase://localhost \
  --username Administrator \
  --password password

The first run is a full backup. Subsequent runs are incremental — only new/changed data is transferred.

Useful flags

Flag	Purpose
--threads <n>	Concurrent backup clients (default 1; don't exceed CPU count)
--full-backup	Force a full backup in the same repository
--resume	Resume a previously interrupted backup
--purge	Discard a partial backup and restart from last successful
--no-progress-bar	Suppress progress output (useful in cron/CI)
--value-compression compressed	Compress values on disk (default)

TLS / Capella

cbbackupmgr backup \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --cluster couchbases://cb.xxxxx.cloud.couchbase.com \
  --username backup-user \
  --password password \
  --cacert /path/to/ca.pem

---

Step 3 — Merge Snapshots

Merging combines multiple incremental snapshots into one, reclaiming disk space without touching the cluster.

# Merge snapshots 1 through 7 into a single snapshot
cbbackupmgr merge \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --start 1 \
  --end 7

---

Step 4 — Restore

cbbackupmgr restore \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --cluster couchbase://localhost \
  --username Administrator \
  --password password

Restore a specific time range

cbbackupmgr restore \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --cluster couchbase://localhost \
  --username Administrator \
  --password password \
  --start 2024-06-01T00:00:00Z \
  --end 2024-06-03T00:00:00Z

Restore specific buckets/scopes/collections

# Restore only the 'orders' scope from 'myapp' bucket
cbbackupmgr restore \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --cluster couchbase://localhost \
  --username Administrator \
  --password password \
  --include-data myapp.orders

Remap to a different bucket/collection

# Restore 'myapp' data into 'myapp-restored'
cbbackupmgr restore \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --cluster couchbase://localhost \
  --username Administrator \
  --password password \
  --map-data myapp=myapp-restored

Key restore flags

Flag	Purpose
--start / --end	Restore a time range of snapshots
--include-data	Comma-separated bucket/scope/collection filter
--exclude-data	Exclude specific data
--map-data	Remap source → target bucket/collection
--force-updates	Overwrite existing documents (default: skip if newer)
--threads <n>	Concurrent restore clients
--no-progress-bar	Suppress progress output

---

Backup Strategies

Recommended: Periodic Merge

Take daily incremental backups; merge the previous week's snapshots each Sunday. Lowest cluster overhead — no full backups needed.

# Daily cron (runs every day)
cbbackupmgr backup \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --cluster couchbase://localhost \
  --username backup-user \
  --password "$CB_PASSWORD" \
  --no-progress-bar

# Weekly merge cron (runs every Sunday after backup)
cbbackupmgr merge \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --start 1 \
  --end 7

Full/Incremental

Create a new repository each week (full backup), then take daily incrementals. Simpler retention management — delete old repositories to free space. Suitable for small-to-medium clusters.

# Weekly: create new repo and take full backup
REPO="cluster-$(date +%Y-W%V)"
cbbackupmgr config --archive /backup-archive --repo "$REPO"
cbbackupmgr backup \
  --archive /backup-archive \
  --repo "$REPO" \
  --cluster couchbase://localhost \
  --username backup-user \
  --password "$CB_PASSWORD" \
  --no-progress-bar

# Daily: incremental into current week's repo
cbbackupmgr backup \
  --archive /backup-archive \
  --repo "$REPO" \
  --cluster couchbase://localhost \
  --username backup-user \
  --password "$CB_PASSWORD" \
  --no-progress-bar

---

Scheduling Backups

See references/scheduling.md for cron and systemd timer examples.

---

Cloud Object Storage (Enterprise, Server 6.6+)

Supports AWS S3 (s3://), GCS (gs://), and Azure Blob Storage (az://). Use IAM roles or CB_OBJSTORE_ACCESS_KEY_ID / CB_OBJSTORE_SECRET_ACCESS_KEY env vars — avoid inline credentials. A staging directory is required; do not use /tmp.

See references/cloud-backup.md for full S3/GCS/Azure examples and KMS encryption.

---

Inspect and Manage

# List all snapshots in a repository
cbbackupmgr list \
  --archive /backup-archive \
  --repo my-cluster-repo

# Show detailed info (document counts, sizes)
cbbackupmgr list \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --long

# Remove a specific snapshot
cbbackupmgr remove \
  --archive /backup-archive \
  --repo my-cluster-repo \
  --backups 2024-06-01T00:00:00Z

# Validate archive integrity
cbbackupmgr examine \
  --archive /backup-archive \
  --repo my-cluster-repo

---

RBAC — Minimum Required Roles

The backup user needs data_backup on each bucket and ro_admin for cluster configuration. See security skill for user creation details.

---

Troubleshooting

Partial backup: if a backup is interrupted, re-run with --resume to continue from where it stopped, or --purge to discard and restart from the last successful snapshot.

Rebalance during backup: cbbackupmgr handles rebalance by tracking data movement. Expect higher resource usage — reduce --threads if cluster performance degrades.

Node failure during backup: the tool waits 180 seconds for the node to recover or be failed over. If neither happens, the affected node's data is marked failed and the backup continues as partial.

Cloud staging directory: never delete individual subdirectories inside the staging dir — remove the entire directory if cleanup is needed.