/frappe-ops-backup

name: frappe-ops-backup
description: >
  Use when configuring backups, restoring sites, encrypting backup files, scheduling automated backups, or planning disaster recovery.
  Prevents data loss from missing backups, failed restores, and unencrypted sensitive data.
  Covers bench backup, bench restore, backup encryption, S3/remote storage, scheduled backups, disaster recovery procedures.
  Keywords: backup, restore, encryption, S3, scheduled backup, disaster recovery, bench backup, bench restore, how to backup, restore database, backup failed, data recovery, automated backup..
license: MIT
compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
metadata:
  author: OpenAEC-Foundation
  version: "2.0"

Backup & Disaster Recovery

Frappe provides built-in backup and restore commands via bench. ALWAYS back up before updates, migrations, or any destructive operation. A backup that has never been test-restored is NOT a backup.

Quick Reference

# Database-only backup (default)
bench backup

# Full backup with public + private files
bench backup --with-files

# Backup specific site
bench --site mysite.com backup --with-files

# Backup with compression (.tgz instead of .tar)
bench backup --with-files --compress

# Backup only specific DocTypes
bench backup --only "Sales Invoice,Purchase Invoice"

# Backup excluding specific DocTypes
bench backup --exclude "Error Log,Activity Log"

# Custom backup path
bench backup --backup-path /mnt/backups/

# Restore from backup
bench --site mysite.com restore /path/to/backup.sql.gz

# Restore with files
bench --site mysite.com restore /path/to/backup.sql.gz \
    --with-public-files /path/to/files.tar \
    --with-private-files /path/to/private-files.tar

# Setup automated backups (cron)
bench setup backups

What Gets Backed Up

| Component | Default | With --with-files | Location | |---|---|---|---| | Database (SQL dump) | YES | YES | `sites/{site}/private/backups/` | | Site config | YES | YES | `sites/{site}/private/backups/` | | Public files | NO | YES | `sites/{site}/public/files/` | | Private files | NO | YES | `sites/{site}/private/files/` |

**Backup file naming**: `{datetime}_{hash}_{site}-database.sql.gz`

---

Backup Decision Tree

What do you need to back up?
|
+-- Quick database snapshot before a change?
|   +-- bench backup (database only, fast)
|
+-- Full backup before upgrade or migration?
|   +-- bench backup --with-files --compress
|
+-- Automated daily backups?
|   +-- bench setup backups (cron-based)
|   +-- OR S3 Backup Settings (cloud storage)
|
+-- Offsite / cloud backup?
|   +-- S3 Backup Settings DocType (built-in)
|   +-- OR custom script with rclone/aws-cli
|
+-- Partial backup (specific DocTypes)?
|   +-- bench backup --only "DocType1,DocType2"
|
+-- Disaster recovery?
|   +-- Full backup + files + tested restore procedure
|   +-- See Disaster Recovery section below

---

bench backup: All Options

bench backup [OPTIONS]

# Path options
--backup-path PATH              # Save all backup files to this directory
--backup-path-db PATH           # Custom path for database dump
--backup-path-conf PATH         # Custom path for site config backup
--backup-path-files PATH        # Custom path for public files archive
--backup-path-private-files PATH # Custom path for private files archive

# Filter options
--only, --include, -i DOCTYPES  # Include ONLY these DocTypes (comma-separated)
--exclude, -e DOCTYPES          # Exclude these DocTypes (comma-separated)
--ignore-backup-conf            # Ignore include/exclude from site config

# Flags
--with-files                    # Include public and private files
--compress                      # Use .tgz format (gzip compressed tar)
--verbose                       # Show detailed output

**Safety feature**: If backup fails (any exception), partial files are automatically deleted to avoid consuming disk space with incomplete backups.

---

bench restore: All Options

bench --site [site-name] restore [OPTIONS] SQL_FILE_PATH

# SQL_FILE_PATH: path to .sql or .sql.gz file
# Can be relative to sites/ directory or absolute path

# Options
--db-root-username USERNAME     # MariaDB/PostgreSQL root username
--db-root-password PASSWORD     # MariaDB/PostgreSQL root password
--db-name NAME                  # Use custom database name
--admin-password PASSWORD       # Set administrator password after restore
--install-app APP_NAME          # Install app after restore
--with-public-files PATH        # Restore public files (.tar or .tgz)
--with-private-files PATH       # Restore private files (.tar or .tgz)

# Flags
--force                         # Bypass downgrade warnings (NOT recommended)

**CRITICAL**: Downgrades are NOT supported. Restoring a backup from a newer version onto an older version triggers a warning. NEVER use `--force` to bypass this unless you understand the consequences.

---

Automated Backups

Cron-Based (bench setup backups)

# Sets up daily backup cron job
bench setup backups

# This adds to crontab:
# 0 */6 * * * cd /home/frappe/frappe-bench && bench backup --with-files

S3 Backup Settings (Built-in DocType)

Configure in ERPNext: **Settings > S3 Backup Settings**

| Field | Description | |---|---| | Enable | Toggle automated S3 backups | | S3 Bucket Name | Target bucket | | AWS Access Key ID | IAM credentials | | AWS Secret Access Key | IAM secret | | Region | AWS region (e.g., eu-west-1) | | Frequency | Daily, Weekly | | Backup Files | Include public/private files |

# Programmatic S3 backup trigger
from frappe.integrations.offsite_backup_utils import send_email
import frappe

# The S3 backup runs via scheduled job when enabled
# To trigger manually:
from frappe.integrations.doctype.s3_backup_settings.s3_backup_settings import take_backups_s3
take_backups_s3()

Custom Backup Script

#!/bin/bash
# custom-backup.sh — Daily backup with rotation and o