Backup Manager

Backup Manager Skill

This skill implements backup creation, verification, metadata tracking, and retention management.

Example Request

{
  "operation": "create-backup",
  "parameters": {
    "environment": "production",
    "label": "pre-v2-migration",
    "reason": "before major schema changes",
    "compression": true,
    "working_directory": "/mnt/c/GitHub/myorg/myproject"
  }
}

Follow the workflow file at workflow/create-backup.md for detailed step-by-step instructions for backup creation.

High-level process:

1. Output start message with environment and operation
2. Validate environment parameter
3. Set working directory context (CLAUDE_DB_CWD)
4. Load configuration
5. Get environment settings
6. Generate unique backup ID
7. Check disk space requirements
8. Pre-backup checks (database accessible, backup directory exists)
9. Create backup via handler (Prisma/cloud)
10. Verify backup (file exists, readable, valid)
11. Record metadata (backups.json)
12. Output end message with backup details
13. Return structured response

This skill routes to backup tool handlers based on configuration:

• Prisma Local (handler-db-prisma): pg_dump/mysqldump backups
• AWS RDS (handler-cloud-aws): RDS snapshots (future)
• GCP Cloud SQL (handler-cloud-gcp): Cloud SQL backups (future)

Handler is determined from configuration:

• Configuration path: .fractary/plugins/faber-db/config.json
• Field: .database.hosting and .backup.method

Handler Operations:

• create-backup - Create database backup
• verify-backup - Verify backup integrity
• list-backups - List available backups
• delete-backup - Delete backup file

If any step fails:

• Log detailed error
• Clean up partial backup files
• Return error response with recovery suggestions
• DO NOT record failed backup in metadata

Output structured messages:

Start:

🎯 STARTING: Backup Manager
Environment: production
Operation: create-backup
Label: pre-v2-migration
───────────────────────────────────────

During execution, log key steps:

• ✓ Configuration loaded
• ✓ Environment validated: production
• ✓ Backup ID generated: backup-20250124-140000-pre-v2-migration
• ✓ Disk space check: 50 GB available (need 25 GB)
• ✓ Creating backup via Prisma handler
• ✓ Backup file created: 12.3 GB
• ✓ Verifying backup integrity
• ✓ Recording metadata

End (success):

✅ COMPLETED: Backup Manager
Environment: production
Backup ID: backup-20250124-140000-pre-v2-migration
File: .fractary/plugins/faber-db/backups/production/backup-20250124-140000-pre-v2-migration.sql.gz
Size: 12.3 GB
Retention: 90 days (expires: 2025-04-24)
───────────────────────────────────────
To restore from this backup:
  /faber-db:restore production --from backup-20250124-140000-pre-v2-migration

Return JSON:

Success:

{
  "status": "success",
  "operation": "create-backup",
  "environment": "production",
  "result": {
    "backup_id": "backup-20250124-140000-pre-v2-migration",
    "label": "pre-v2-migration",
    "file_path": ".fractary/plugins/faber-db/backups/production/backup-20250124-140000-pre-v2-migration.sql.gz",
    "size_bytes": 13212876800,
    "size_human": "12.3 GB",
    "compressed": true,
    "format": "sql",
    "migrations": {
      "applied_count": 24,
      "last_migration": "20250124130000_add_api_keys"
    },
    "retention_days": 90,
    "expires_at": "2025-04-24T14:00:00Z",
    "verification": {
      "integrity_check": "passed",
      "file_readable": true
    }
  },
  "message": "Backup created successfully for production"
}

Error:

{
  "status": "error",
  "operation": "create-backup",
  "environment": "production",
  "error": "Insufficient disk space",
  "result": {
    "required_space_gb": 25,
    "available_space_gb": 15,
    "backup_size_estimate_gb": 48
  },
  "recovery": {
    "suggestions": [
      "Free up disk space: df -h",
      "Clean up old backups: /faber-db:cleanup-backups --expired",
      "Use compression: --compression flag (default for production)",
      "Use cloud storage: Configure S3 in config.json"
    ]
  }
}

Common errors and handling:

Insufficient Disk Space:

{
  "status": "error",
  "error": "Insufficient disk space for backup",
  "result": {
    "required_space_gb": 50,
    "available_space_gb": 25
  },
  "recovery": {
    "suggestions": [
      "Free up disk space",
      "Use compression: --compression flag",
      "Clean up old backups: /faber-db:cleanup-backups",
      "Configure cloud storage in config.json"
    ]
  }
}

Backup Tool Not Found:

{
  "status": "error",
  "error": "pg_dump not found - PostgreSQL client required",
  "recovery": {
    "suggestions": [
      "Install PostgreSQL client: sudo apt-get install postgresql-client",
      "macOS: brew install postgresql",
      "Windows: Download from postgresql.org",
      "After installation, retry: /faber-db:backup dev"
    ]
  }
}

Database Connection Failed:

{
  "status": "error",
  "error": "Cannot connect to database for backup",
  "prisma_output": "Connection refused at localhost:5432",
  "recovery": {
    "suggestions": [
      "Verify database is running",
      "Check connection string: echo $PROD_DATABASE_URL",
      "Test connection: psql $PROD_DATABASE_URL",
      "Verify network/VPN access"
    ]
  }
}

Backup Verification Failed:

{
  "status": "error",
  "error": "Backup verification failed - file may be corrupted",
  "result": {
    "backup_file": "backup-20250124-140000.sql",
    "expected_size_min_mb": 100,
    "actual_size_mb": 12,
    "file_readable": false
  },
  "recovery": {
    "suggestions": [
      "Delete corrupted backup file",
      "Retry backup creation",
      "Check disk space during backup",
      "Verify database connection stability"
    ]
  }
}

Backup Directory Not Writable:

{
  "status": "error",
  "error": "Cannot write to backup directory",
  "result": {
    "backup_directory": ".fractary/plugins/faber-db/backups/production/",
    "permissions": "dr-xr-xr-x",
    "required": "drwxrwxr-x"
  },
  "recovery": {
    "suggestions": [
      "Fix directory permissions: chmod 775 .fractary/plugins/faber-db/backups",
      "Or create directory: mkdir -p .fractary/plugins/faber-db/backups/production",
      "Verify user has write access"
    ]
  }
}

Migration Deployer Integration

Called by migration-deployer before protected deployments:

{
  "skill": "backup-manager",
  "operation": "create-backup",
  "parameters": {
    "environment": "production",
    "reason": "pre-migration",
    "label": "before-migration-deployment"
  }
}

Returns backup_id for potential rollback:

{
  "status": "success",
  "result": {
    "backup_id": "backup-20250124-140000-pre-migration"
  }
}

Rollback Manager Integration

Provides backup listing for rollback target selection:

{
  "skill": "backup-manager",
  "operation": "list-backups",
  "parameters": {
    "environment": "production",
    "sort": "desc",
    "limit": 5
  }
}

Returns available backups:

{
  "status": "success",
  "result": {
    "backups": [
      {
        "backup_id": "backup-20250124-140000",
        "created_at": "2025-01-24T14:00:00Z",
        "migrations_count": 24
      }
    ]
  }
}

Backup Tool Handler Integration

For actual backup creation:

1. Determine backup method from configuration:

   • Local database: Use native tools (pg_dump, mysqldump)
   • AWS RDS: Use RDS snapshots
   • GCP Cloud SQL: Use Cloud SQL backups

2. Invoke handler based on hosting provider:

   {
     "skill": "handler-db-prisma",
     "operation": "create-backup",
     "parameters": {
       "environment": "production",
       "database_url_env": "PROD_DATABASE_URL",
       "output_file": ".fractary/plugins/faber-db/backups/production/backup-20250124-140000.sql",
       "compression": true,
       "format": "sql"
     }
   }
   

3. Handler returns:

   • Backup file path
   • File size
   • Duration
   • Success/failure status

Backup Metadata Structure

The backups.json file tracks all backups:

{
  "schema_version": "1.0",
  "backups": [
    {
      "backup_id": "backup-20250124-140000-pre-v2-migration",
      "environment": "production",
      "database_name": "myapp_prod",
      "created_at": "2025-01-24T14:00:00Z",
      "label": "pre-v2-migration",
      "reason": "before major schema changes",
      "file_path": ".fractary/plugins/faber-db/backups/production/backup-20250124-140000-pre-v2-migration.sql.gz",
      "size_bytes": 13212876800,
      "compressed": true,
      "compression_ratio": 0.256,
      "format": "sql",
      "backup_method": "pg_dump",
      "migrations": {
        "applied_count": 24,
        "last_migration": "20250124130000_add_api_keys",
        "migrations_list": [
          "20250120100000_initial_schema",
          "...",
          "20250124130000_add_api_keys"
        ]
      },
      "retention_days": 90,
      "expires_at": "2025-04-24T14:00:00Z",
      "status": "valid",
      "verification": {
        "integrity_check": "passed",
        "file_readable": true,
        "file_exists": true,
        "verified_at": "2025-01-24T14:00:05Z"
      },
      "created_by": "backup-manager",
      "tags": ["production", "pre-migration", "v2-launch"]
    }
  ]
}

Backup ID Format

Backup IDs follow a consistent format:

backup-YYYYMMDD-HHMMSS[-label]

Examples:

• backup-20250124-140000 - Auto-generated
• backup-20250124-140000-pre-migration - With pre-migration label
• backup-20250124-140000-pre-v2-migration - With custom label

The timestamp ensures uniqueness and chronological sorting.

Disk Space Calculation

Before creating backup, estimate required space:

1. Query database size: SELECT pg_database_size('myapp_prod')
2. Add 20% buffer for safety
3. If compression enabled, estimate 70% reduction (varies by data)
4. Check available disk space: df -h
5. Proceed if sufficient space, error otherwise

Example:

Database size: 45 GB
Buffer (20%): 9 GB
Total estimate: 54 GB
With compression (70% reduction): 16 GB
Available space: 50 GB
Result: ✓ Sufficient space

Retention Management

Backups are automatically managed based on retention:

• Development: 30 days (default)
• Staging: 60 days (default)
• Production: 90 days (default)

Cleanup process:

1. List backups older than retention period
2. Exclude backups with special labels (manual, important)
3. Delete expired backup files
4. Remove from backups.json metadata

Manual override:

/faber-db:backup production --retention 180  # 180 days

Safety Backups

Automatic safety backups before:

• Production migrations (backup-*-pre-migration)
• Rollback operations (backup-*-pre-rollback)
• Destructive operations (backup-*-pre-operation)

Safety backups have extended retention (90 days minimum).

Notes

• Idempotent: Can safely run multiple times (generates unique IDs)
• Non-blocking: Large backups show progress indicators
• Atomic: Backup file only recorded in metadata after verification
• Resumable: Failed backups can be retried (partial files cleaned up)
• Monitored: All operations logged for audit trail