quality_app/documentation/BACKUP_SCHEDULE_FEATURE.md

Backup Schedule Feature - Complete Guide

Overview

The backup schedule feature allows administrators to configure automated backups that run at specified times with customizable frequency. This ensures regular, consistent backups without manual intervention.

Added: November 5, 2025 Version: 1.1.0

---

Key Features

1. Automated Scheduling

• Daily Backups: Run every day at specified time
• Weekly Backups: Run once per week
• Monthly Backups: Run once per month
• Custom Time: Choose exact time (24-hour format)

2. Backup Type Selection ✨ NEW

• Full Backup: Complete database with schema, triggers, and data
• Data-Only Backup: Only table data (faster, smaller files)

3. Retention Management

• Automatic Cleanup: Delete backups older than X days
• Configurable Period: Keep backups from 1 to 365 days
• Smart Storage: Prevents disk space issues

4. Easy Management

• Enable/Disable: Toggle scheduled backups on/off
• Visual Interface: Clear, intuitive settings panel
• Status Tracking: See current schedule at a glance

---

Configuration Options

Schedule Settings

Setting	Options	Default	Description
Enabled	On/Off	Off	Enable or disable scheduled backups
Time	00:00 - 23:59	02:00	Time to run backup (24-hour format)
Frequency	Daily, Weekly, Monthly	Daily	How often to run backup
Backup Type	Full, Data-Only	Full	Type of backup to create
Retention	1-365 days	30	Days to keep old backups

---

Recommended Configurations

Configuration 1: Daily Data Snapshots

Best for: Production environments with frequent data changes

{
  "enabled": true,
  "time": "02:00",
  "frequency": "daily",
  "backup_type": "data-only",
  "retention_days": 7
}

Why:

• ✅ Fast daily backups (data-only is 30-40% faster)
• ✅ Smaller file sizes
• ✅ 7-day retention keeps recent history without filling disk
• ✅ Schema changes handled separately

Configuration 2: Weekly Full Backups

Best for: Stable environments, comprehensive safety

{
  "enabled": true,
  "time": "03:00",
  "frequency": "weekly",
  "backup_type": "full",
  "retention_days": 60
}

Why:

• ✅ Complete database backup with schema and triggers
• ✅ Less frequent (lower storage usage)
• ✅ 60-day retention for long-term recovery
• ✅ Safe for disaster recovery

Configuration 3: Hybrid Approach (Recommended)

Best for: Most production environments

Schedule 1 - Daily Data:

{
  "enabled": true,
  "time": "02:00",
  "frequency": "daily",
  "backup_type": "data-only",
  "retention_days": 7
}

Schedule 2 - Weekly Full (manual or separate scheduler):

• Run manual full backup every Sunday
• Keep for 90 days

Why:

• ✅ Daily data snapshots for quick recovery
• ✅ Weekly full backups for complete safety
• ✅ Balanced storage usage
• ✅ Multiple recovery points

---

How to Configure

Via Web Interface

1. Navigate to Settings:

   • Log in as Admin or Superadmin
   • Go to Settings page
   • Scroll to Database Backup Management section

2. Configure Schedule:

   • Check "Enable Scheduled Backups" checkbox
   • Set Backup Time (e.g., 02:00)
   • Choose Frequency (Daily/Weekly/Monthly)
   • Select Backup Type:
     • Full Backup for complete safety
     • Data-Only Backup for faster, smaller backups
   • Set Retention Days (1-365)

3. Save Configuration:

   • Click 💾 Save Schedule button
   • Confirm settings in alert message

Via Configuration File

File Location: /srv/quality_app/backups/backup_schedule.json

Example:

{
  "enabled": true,
  "time": "02:00",
  "frequency": "daily",
  "backup_type": "data-only",
  "retention_days": 30
}

Note: Changes take effect on next scheduled run.

---

Technical Implementation

1. Schedule Storage

• File: backup_schedule.json in backups directory
• Format: JSON
• Persistence: Survives application restarts

2. Backup Execution

The schedule configuration is stored, but actual execution requires a cron job or scheduler:

Recommended: Use system cron

# Edit crontab
crontab -e

# Add entry for 2 AM daily
0 2 * * * cd /srv/quality_app/py_app && /srv/quality_recticel/recticel/bin/python3 -c "from app.database_backup import DatabaseBackupManager; from app import create_app; app = create_app(); app.app_context().push(); mgr = DatabaseBackupManager(); schedule = mgr.get_backup_schedule(); mgr.create_data_only_backup() if schedule['backup_type'] == 'data-only' else mgr.create_backup()"

Alternative: APScheduler (application-level)

from apscheduler.schedulers.background import BackgroundScheduler

scheduler = BackgroundScheduler()

def scheduled_backup():
    schedule = backup_manager.get_backup_schedule()
    if schedule['enabled']:
        if schedule['backup_type'] == 'data-only':
            backup_manager.create_data_only_backup()
        else:
            backup_manager.create_backup()
        backup_manager.cleanup_old_backups(schedule['retention_days'])

# Schedule based on configuration
scheduler.add_job(scheduled_backup, 'cron', hour=2, minute=0)
scheduler.start()

3. Cleanup Process

Automated cleanup runs after each backup:

• Scans backup directory
• Identifies files older than retention_days
• Deletes old backups
• Logs deletion activity

---

Backup Type Comparison

Full Backup (Schema + Data + Triggers)

mysqldump command:

mysqldump \
  --single-transaction \
  --skip-lock-tables \
  --force \
  --routines \
  --triggers \        # ✅ Included
  --events \
  --add-drop-database \
  --databases trasabilitate

Typical size: 1-2 MB (schema) + data size Backup time: ~15-30 seconds Restore: Complete replacement

Data-Only Backup

mysqldump command:

mysqldump \
  --no-create-info \      # ❌ Skip CREATE TABLE
  --skip-triggers \       # ❌ Skip triggers
  --no-create-db \        # ❌ Skip CREATE DATABASE
  --complete-insert \
  --extended-insert \
  --single-transaction \
  trasabilitate

Typical size: Data size only Backup time: ~10-20 seconds (30-40% faster) Restore: Data only (schema must exist)

---

Understanding the UI

Schedule Form Fields

┌─────────────────────────────────────────────┐
│ ☑ Enable Scheduled Backups                 │
├─────────────────────────────────────────────┤
│ Backup Time: [02:00]                        │
│ Frequency: [Daily ▼]                        │
│ Backup Type: [Full Backup ▼]               │
│ Keep backups for: [30] days                │
├─────────────────────────────────────────────┤
│        [💾 Save Schedule]                   │
└─────────────────────────────────────────────┘

💡 Recommendation: Use Full Backup for weekly/
   monthly schedules (complete safety), and
   Data-Only for daily schedules (faster,
   smaller files).

Success Message Format

When saving schedule:

✅ Backup schedule saved successfully

Scheduled [Full/Data-Only] backups will run 
[daily/weekly/monthly] at [HH:MM].

---

API Endpoints

Get Current Schedule

GET /api/backup/schedule

Response:

{
  "success": true,
  "schedule": {
    "enabled": true,
    "time": "02:00",
    "frequency": "daily",
    "backup_type": "data-only",
    "retention_days": 30
  }
}

Save Schedule

POST /api/backup/schedule
Content-Type: application/json

{
  "enabled": true,
  "time": "02:00",
  "frequency": "daily",
  "backup_type": "data-only",
  "retention_days": 30
}

Response:

{
  "success": true,
  "message": "Backup schedule saved successfully"
}

---

Monitoring and Logs

Check Backup Files

ls -lh /srv/quality_app/backups/*.sql | tail -10

Verify Schedule Configuration

cat /srv/quality_app/backups/backup_schedule.json

Check Application Logs

tail -f /srv/quality_app/logs/error.log | grep -i backup

Monitor Disk Usage

du -sh /srv/quality_app/backups/

---

Troubleshooting

Issue: Scheduled backups not running

Check 1: Is schedule enabled?

cat /srv/quality_app/backups/backup_schedule.json | grep enabled

Check 2: Is cron job configured?

crontab -l | grep backup

Check 3: Are there permission issues?

ls -la /srv/quality_app/backups/

Solution: Ensure cron job exists and has proper permissions.

---

Issue: Backup files growing too large

Check disk usage:

du -sh /srv/quality_app/backups/
ls -lh /srv/quality_app/backups/*.sql | wc -l

Solutions:

1. Reduce retention_days (e.g., from 30 to 7)
2. Use data-only backups (smaller files)
3. Store old backups on external storage
4. Compress backups: gzip /srv/quality_app/backups/*.sql

---

Issue: Data-only restore fails

Error: "Table doesn't exist"

Cause: Database schema not present

Solution:

1. Run full backup restore first, OR
2. Ensure database structure exists via setup script

---

Best Practices

✅ DO:

1. Enable scheduled backups - Automate for consistency
2. Use data-only for daily - Faster, smaller files
3. Use full for weekly - Complete safety net
4. Test restore regularly - Verify backups work
5. Monitor disk space - Prevent storage issues
6. Store off-site copies - Disaster recovery
7. Adjust retention - Balance safety vs. storage

❌ DON'T:

1. Don't disable all backups - Always have some backup
2. Don't set retention too low - Keep at least 7 days
3. Don't ignore disk warnings - Monitor storage
4. Don't forget to test restores - Untested backups are useless
5. Don't rely only on scheduled - Manual backups before major changes

---

Security and Access

Required Roles

• View Schedule: Admin, Superadmin
• Edit Schedule: Admin, Superadmin
• Execute Manual Backup: Admin, Superadmin
• Restore Database: Superadmin only

File Permissions

# Backup directory
drwxrwxr-x /srv/quality_app/backups/

# Schedule file
-rw-rw-r-- backup_schedule.json

# Backup files
-rw-rw-r-- *.sql

---

Migration Guide

Upgrading from Previous Version (without backup_type)

Automatic: Schedule automatically gets backup_type: "full" on first load

Manual update:

cd /srv/quality_app/backups/
# Backup current schedule
cp backup_schedule.json backup_schedule.json.bak

# Add backup_type field
cat backup_schedule.json | jq '. + {"backup_type": "full"}' > backup_schedule_new.json
mv backup_schedule_new.json backup_schedule.json

---

Related Documentation

• DATA_ONLY_BACKUP_FEATURE.md - Data-only backup details
• BACKUP_SYSTEM.md - Complete backup system overview
• QUICK_BACKUP_REFERENCE.md - Quick reference guide

---

Future Enhancements

Planned Features:

• Multiple schedules (daily data + weekly full)
• Email notifications on backup completion
• Backup to remote storage (S3, FTP)
• Backup compression (gzip)
• Backup encryption
• Web-based backup browsing
• Automatic restore testing

---

Last Updated: November 5, 2025 Module: app/database_backup.py UI Template: app/templates/settings.html Application: Quality Recticel - Trasabilitate System