Petbot/BACKUP_SYSTEM_INTEGRATION.md

PetBot Backup System Integration Guide

Overview

The PetBot backup system provides automated database backups with rotation, compression, and restore capabilities. This system ensures data protection and disaster recovery for the PetBot project.

Components

1. Core Backup Module (src/backup_manager.py)

Features:

• Automated database backups using SQLite backup API
• Gzip compression for space efficiency
• Retention policies (7 daily, 4 weekly, 12 monthly)
• Backup verification and integrity checks
• Restore functionality with automatic current database backup
• Database structure export for documentation

Key Classes:

• BackupManager: Main backup operations
• BackupScheduler: Automated scheduling system

2. IRC Command Module (modules/backup_commands.py)

Commands:

• !backup [type] [uncompressed] - Create manual backup
• !restore <filename> [confirm] - Restore from backup
• !backups - List available backups
• !backup_stats - Show backup statistics
• !backup_cleanup - Clean up old backups

Security:

• Admin-only commands
• Confirmation required for restore operations
• Automatic current database backup before restore

3. Configuration (config/backup_config.json)

Settings:

• Backup retention policies
• Compression settings
• Automated schedule configuration
• Monitoring and notification preferences

Installation

1. Dependencies

Ensure the following Python packages are installed:

pip install aiosqlite

2. Directory Structure

Create the backup directory:

mkdir -p backups

3. Integration with Bot

Add the backup commands module to your bot's module loader in src/bot.py:

from modules.backup_commands import BackupCommands

# In your bot initialization
self.backup_commands = BackupCommands(self, self.database)

4. Configuration

Update modules/backup_commands.py with your admin usernames:

admin_users = ["admin", "your_username"]  # Replace with actual admin usernames

Usage

Manual Backup Creation

!backup                    # Create manual compressed backup
!backup uncompressed       # Create uncompressed backup
!backup daily             # Create daily backup

Listing Backups

!backups                   # List available backups
!backup_stats             # Show detailed statistics

Restore Operations

!restore backup_filename.db.gz         # Show restore confirmation
!restore backup_filename.db.gz confirm # Actually perform restore

Maintenance

!backup_cleanup           # Remove old backups per retention policy

Automated Scheduling

The backup system automatically creates:

• Daily backups: Every 24 hours
• Weekly backups: Every 7 days
• Monthly backups: Every 30 days

Automated cleanup removes old backups based on retention policy:

• Keep 7 most recent daily backups
• Keep 4 most recent weekly backups
• Keep 12 most recent monthly backups

Monitoring

Log Messages

The backup system logs important events:

• Backup creation success/failure
• Restore operations
• Cleanup operations
• Scheduler status

Statistics

Use !backup_stats to monitor:

• Total backup count and size
• Backup age information
• Breakdown by backup type

Security Considerations

1. Access Control: Only admin users can execute backup commands
2. Confirmation: Restore operations require explicit confirmation
3. Safety Backup: Current database is automatically backed up before restore
4. Integrity Checks: All backups are verified after creation

Directory Structure

backups/
├── petbot_backup_daily_20240115_030000.db.gz
├── petbot_backup_weekly_20240114_020000.db.gz
├── petbot_backup_monthly_20240101_010000.db.gz
└── database_structure_20240115_120000.json

Backup Filename Format

petbot_backup_{type}_{timestamp}.db[.gz]

• {type}: daily, weekly, monthly, manual
• {timestamp}: YYYYMMDD_HHMMSS format
• .gz: Added for compressed backups

Troubleshooting

Common Issues

1. Permission Errors: Ensure backup directory is writable
2. Disk Space: Monitor available space, backups are compressed by default
3. Database Locked: Backups use SQLite backup API to avoid locking issues

Recovery Procedures

1. Database Corruption: Use most recent backup with !restore
2. Backup Corruption: Try previous backup or use database structure export
3. Complete Loss: Restore from most recent backup, may lose recent data

Testing

Run the test suite to verify functionality:

python3 test_backup_simple.py

This tests:

• Basic backup creation
• Compression functionality
• Restore operations
• Directory structure
• Real database compatibility

Performance

Backup Sizes

• Uncompressed: ~2-5MB for typical database
• Compressed: ~200-500KB (60-90% reduction)

Backup Speed

• Small databases (<10MB): 1-2 seconds
• Medium databases (10-100MB): 5-10 seconds
• Large databases (>100MB): 30+ seconds

Future Enhancements

1. Encryption: Add backup encryption for sensitive data
2. Remote Storage: Support for cloud storage providers
3. Differential Backups: Only backup changed data
4. Web Interface: Backup management through web interface
5. Email Notifications: Alert on backup failures

Support

For issues or questions about the backup system:

1. Check the logs for error messages
2. Run the test suite to verify functionality
3. Ensure all dependencies are installed
4. Verify directory permissions

Version History

• v1.0: Initial implementation with basic backup/restore
• v1.1: Added compression and automated scheduling
• v1.2: Added IRC commands and admin controls
• v1.3: Added comprehensive testing and documentation