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:
```bash
pip install aiosqlite
```

### 2. Directory Structure

Create the backup directory:
```bash
mkdir -p backups
```

### 3. Integration with Bot

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

```python
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:

```python
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:

```bash
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