# Quick Start Guide - Ngauge SQL Backup Plugin

## Installation Complete! ✓

The `portalpeople/ngauge-backup-sql` plugin has been successfully installed and configured.

## Quick Test

### 1. List Available Database Tables

To see what tables are available for backup (interactive mode will show you this):

```bash
php yii db-backup/create
```

### 2. Create Your First Backup

**Interactive mode (recommended for first-time users):**
```bash
php yii db-backup/create
# Select a table from the list by number or name
```

**Direct command (faster for scripts):**
```bash
php yii db-backup/create --table=users
php yii db-backup/create --table=pricing --filename=pricing-before-update.sql.gz
```

### 3. List All Backups

```bash
php yii db-backup/list

# Filter by specific table
php yii db-backup/list --table=pricing
```

### 4. Restore from Backup

**Interactive mode:**
```bash
php yii db-backup/restore
# Select a backup from the list
```

**Direct command:**
```bash
php yii db-backup/restore --file=users_20260210_1430.sql.gz
```

## Programmatic Usage

Use the static `Backup` facade anywhere in your PHP code:

```php
use PortalPeople\NgaugeBackupSql\components\Backup;

// Create a backup
$backupFile = Backup::SQLTable('pricing');
echo "Backup created: $backupFile\n";

// Create backup with custom filename  
$backupFile = Backup::SQLTable('pricing', 'pricing-ADP.zip');

// List restore points for a table
$restorePoints = Backup::listRestorePoints('pricing');
foreach ($restorePoints as $point) {
    echo "{$point['filename']} - {$point['size_formatted']}\n";
}

// Restore from backup
Backup::restore('pricing_20260210_1430.sql.gz');
```

## Backend Web UI

Access the backup management interface at:

```
https://your-domain.com/db-backup
```

Features:
- ✓ Visual table selection with checkboxes
- ✓ One-click backup creation
- ✓ Browse restore points by table
- ✓ Download backup files
- ✓ Restore with confirmation

## Queue Integration (Async Backups)

Schedule backups to run in the background:

```php
use PortalPeople\NgaugeBackupSql\jobs\DatabaseBackupJob;

// Queue a backup job for specific tables
Yii::$app->queue->push(new DatabaseBackupJob([
    'tables' => ['users', 'pricing', 'orders'],
    'compress' => true,
]));

// Backup all tables
Yii::$app->queue->push(new DatabaseBackupJob([
    'tables' => ['*'],
    'compress' => true,
    'runCleanup' => true,  // Auto-cleanup old backups
]));
```

## Automated Cleanup

Remove old backups based on retention policy:

```bash
# Use configured retention period (30 days by default)
php yii db-backup/cleanup

# Override retention period
php yii db-backup/cleanup --days=7

# Skip confirmation prompt
php yii db-backup/cleanup --force
```

## Configuration

The plugin is configured in `console/config/main.php` and `backend/config/main.php`:

```php
'modules' => [
    'db-backup' => [
        'class' => 'PortalPeople\NgaugeBackupSql\Module',
        'backupPath' => '@backups/sql',           // Storage location
        'retentionDays' => 30,                     // Keep backups for 30 days
        'compressBackups' => true,                 // Use gzip compression
        'excludeTables' => ['log', 'queue', 'session'], // Tables to hide from listings
        'dbComponent' => 'db',                     // Database component name
    ],
],
```

## File Structure

Backups are stored in:
```
/var/www/vhosts/sb.ion-club.net/surf.sb.ion-club.net/backups/sql/
```

Naming convention:
```
{tablename}_{YYYYMMDD}_{HHMM}.sql.gz

Examples:
- users_20260210_1430.sql.gz
- pricing_20260209_0900.sql.gz
- orders_20260208_1600.sql.gz
```

## Migration (Backup History Tracking)

To enable backup history tracking, run the migration:

```bash
php yii migrate --migrationPath=@PortalPeople/NgaugeBackupSql/migrations
```

This creates a `backup_history` table that tracks all backup/restore operations.

## Troubleshooting

### Command not found: mysqldump

Install MySQL client tools:
```bash
# Ubuntu/Debian
sudo apt-get install mysql-client

# Verify installation
which mysqldump
```

### Permission denied on backup directory

```bash
# Create directory if it doesn't exist
mkdir -p /var/www/vhosts/sb.ion-club.net/surf.sb.ion-club.net/backups/sql

# Set permissions
chmod 755 /var/www/vhosts/sb.ion-club.net/surf.sb.ion-club.net/backups/sql
```

### Backup fails for large tables

For tables larger than 1GB:
1. Increase PHP memory limit and execution time
2. Consider using the queue system for async execution
3. Run backups during off-peak hours

## Next Steps

1. **Run migration** to enable backup history:
   ```bash
   php yii migrate --migrationPath=@PortalPeople/NgaugeBackupSql/migrations
   ```

2. **Test backup creation**:
   ```bash
   php yii db-backup/create --table=users
   ```

3. **Schedule automated backups** using cron:
   ```cron
   # Daily backup at 2 AM
   0 2 * * * cd /var/www/vhosts/sb.ion-club.net/surf.sb.ion-club.net && php yii db-backup/create --table=users --compress=1
   ```

4. **Setup weekly cleanup**:
   ```cron
   # Weekly cleanup on Sunday at 3 AM
   0 3 * * 0 cd /var/www/vhosts/sb.ion-club.net/surf.sb.ion-club.net && php yii db-backup/cleanup --force
   ```

## Support

For issues or questions:
- Email: a.pickstock@PortalPeople.uk
- Documentation: See README.md in `vendor/portalpeople/ngauge-backup-sql/`

---

**Installation Date:** February 10, 2026
**Plugin Version:** 1.0.0-dev
**Status:** ✅ Ready to use
