Backup System

The Fuwafuwa Framework includes a comprehensive database backup system that helps you protect your data with automated backups, integrity verification, and easy restoration. Whether you're deploying updates, migrating data, or simply safeguarding against accidents, this system ensures your database is always recoverable.

Data loss can be catastrophic for any application. The backup system addresses this by providing a reliable, automated way to create point-in-time snapshots of your database. With gzip compression achieving approximately 80% size reduction, backups are efficient to store and fast to transfer. SHA-256 checksums verify integrity, ensuring that when you need to restore, your data is exactly as it was when backed up.

The system is designed with safety at its core. Before any restore operation, a safety backup is automatically created, protecting you against accidental data loss during the restore process itself. Retention policies help manage disk space by automatically cleaning up older backups while preserving the most recent ones.

CLI Commands

The command-line interface provides complete control over backup operations, making it ideal for automation scripts, cron jobs, and deployment workflows. All commands follow a consistent pattern and provide clear feedback about their operations.

Create Backup

Creating backups is straightforward and can be done at any time. Adding a descriptive label helps you identify the purpose of each backup later, especially when maintaining multiple backups for different reasons (pre-deployment, pre-migration, etc.).

# Basic backup
php index.php fuwafuwa/backup/create

# With description
php index.php fuwafuwa/backup/create --description="Before deployment"

Creating Backup

[OK] Backup created successfully!

Filename: backup_20250125_143022_before_deployment.sql.gz
Original size: 119.73KB
Compressed size: 22.22KB
Compression: 81.44%
Checksum: aadd5ebffe924b4de1049e7fa8e7e9743121cf2ad59ba0952ae84a8a500163fb

List Backups

Viewing all available backups helps you understand your backup history and choose which one to restore. The default table format provides a clear overview, while JSON output is useful for scripts and automation.

# Table format (default)
php index.php fuwafuwa/backup/list

# JSON format
php index.php fuwafuwa/backup/list --format=json

Verify Backup

Before trusting a backup—especially one transferred over a network or stored for a long time—verify its integrity using the checksum. This ensures the file hasn't been corrupted or tampered with.

php index.php fuwafuwa/backup/verify --file=backup_20250125_143022.sql.gz

Restore Backup

Restoring a database is a critical operation that replaces your current data with the backed-up version. The system requires explicit confirmation to prevent accidental data loss. Before any restore, a safety backup is automatically created, giving you a fallback if the restore doesn't go as planned.

# Preview (shows warning)
php index.php fuwafuwa/backup/restore --file=backup_20250125_143022.sql.gz

# Execute restore
php index.php fuwafuwa/backup/restore --file=backup_20250125_143022.sql.gz --confirm

Delete Backup

When you no longer need a backup, you can delete it to free up disk space. Like restore operations, deletion requires confirmation to prevent accidental loss of backup data. Consider using the cleanup command instead for automated retention management.

php index.php fuwafuwa/backup/delete --file=backup_20250125_143022.sql.gz --confirm

Cleanup Old Backups

Managing disk space is important for long-running applications. The cleanup command automatically removes older backups while keeping the most recent ones. This is particularly useful when combined with cron jobs for automated maintenance.

# Keep 10 most recent (default)
php index.php fuwafuwa/backup/cleanup

# Keep 5 most recent
php index.php fuwafuwa/backup/cleanup --keep=5

AJAX API

The backup system provides AJAX endpoints for integrating backup functionality into custom administrative interfaces. These endpoints can be used to build custom backup management UIs or integrate with external tools.

Available Endpoints

Configuration

The backup system can be configured through RBAC settings to control which users can perform backup operations. Add these permissions to app/configs/rbac_permission.json to define which user roles can perform specific backup actions:

{
    "backup": {
        "all": {
            "label": "Full Backup Access",
            "paths": ["/ajax/backup/*"]
        },
        "create": {
            "label": "Create Backup",
            "paths": ["/ajax/backup/create"]
        },
        "download": {
            "label": "Download Backup",
            "paths": ["/ajax/backup/download/*"]
        },
        "delete": {
            "label": "Delete Backup",
            "paths": ["/ajax/backup/delete"]
        },
        "restore": {
            "label": "Restore Backup",
            "paths": ["/ajax/backup/restore"]
        },
        "view": {
            "label": "View Backups",
            "paths": ["/ajax/backup/list", "/ajax/backup/info/*"]
        },
        "cli": {
            "label": "CLI Backup",
            "paths": ["/fuwafuwa/backup/*"]
        }
    }
}

These permission levels allow fine-grained control. For example, you can give some users the ability to view backups without allowing them to restore, or allow backup creation without deletion rights. The cli permission enables command-line access for automation scripts.

Backup Storage

Understanding where and how backups are stored helps you plan your storage strategy and implement off-site backup solutions. The backup system uses a combination of filesystem storage for the backup files and database metadata for tracking and quick access.

Storage Design

The naming convention includes timestamps to the second, ensuring unique filenames even when creating multiple backups in quick succession. Optional descriptions in the filename make it easy to identify the purpose of each backup without querying the database. Safety backups created before restore operations are automatically marked with pre_restore in their description.

Filename Examples

• backup_20250125_143022.sql.gz
• backup_20250125_143022_before_deployment.sql.gz
• backup_20250125_143022_pre_restore.sql.gz (safety backup)

Database Schema

The backup system tracks metadata about each backup in a dedicated database table. This enables quick querying of backup history, restore statistics, and efficient cleanup operations. The schema is designed to support both current functionality and future enhancements.

The backup system requires the backup_metadata table:

CREATE TABLE IF NOT EXISTS backup_metadata (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    filename TEXT NOT NULL UNIQUE,
    filepath TEXT NOT NULL,
    size_bytes INTEGER NOT NULL,
    checksum TEXT NOT NULL,
    created_at TEXT NOT NULL,
    created_by TEXT,
    description TEXT,
    status TEXT DEFAULT 'complete',
    restore_count INTEGER DEFAULT 0,
    last_restored_at TEXT
);

Run migration:

sqlite3 app/db/fuwafuwa.db < app/db/migrations/20250125_create_backup_metadata.sql

The restore_count field tracks how many times each backup has been restored, providing insight into which backups are being used and how often. The status field allows for future states like "in_progress" or "failed" for more complex backup scenarios.

Example Workflow

A typical backup workflow integrates with your deployment process, ensuring you always have a rollback option before making database changes. Here's a recommended workflow for deploying schema changes:

# 1. Create backup before deployment
php index.php fuwafuwa/backup/create --description="Pre-deployment"

# 2. Make changes to database

# 3. If something goes wrong, restore
php index.php fuwafuwa/backup/restore \
  --file=backup_20250125_143022_pre_deployment.sql.gz \
  --confirm

# 4. Clean up old backups (keep 10)
php index.php fuwafuwa/backup/cleanup --keep=10

This workflow ensures you always have a recent safety net before making changes. If something goes wrong during deployment, you can immediately restore to the previous state. The cleanup step at the end manages disk space by removing old backups that are no longer needed.