dbbackup/TUI_IMPROVEMENTS.md

# Interactive TUI Experience Improvements

## Current Issues & Solutions

### 1. **Progress Visibility During Long Operations**

**Problem**: Cluster backup/restore with large databases (40GB+) takes 30+ minutes with minimal feedback.

**Solutions**:
- ✅ Show current database being processed
- ✅ Display database size before backup/restore starts
- ✅ ETA estimator for multi-database operations
- 🔄 **NEW**: Real-time progress bar per database (bytes processed / total bytes)
- 🔄 **NEW**: Show current operation speed (MB/s)
- 🔄 **NEW**: Percentage complete for entire cluster operation

### 2. **Error Handling & Recovery**

**Problem**: When restore fails (like resydb with 2.5M errors), user has no context about WHY or WHAT to do.

**Solutions**:
- ✅ Distinguish ignorable errors (already exists) from critical errors
- 🔄 **NEW**: Show error classification in TUI:
  ```
  ⚠️  WARNING: 5 ignorable errors (objects already exist)
  ❌ CRITICAL: Syntax errors detected - dump file may be corrupted
  💡 HINT: Re-create backup with: dbbackup backup single resydb
  ```
- 🔄 **NEW**: Offer retry option for failed databases
- 🔄 **NEW**: Skip vs Abort choice for non-critical failures

### 3. **Large Object Detection Feedback**

**Problem**: User doesn't know WHY parallelism was reduced.

**Solution**:
```
🔍 Scanning cluster backup for large objects...
   ✓ postgres: No large objects
   ⚠️  d7030: 35,000 BLOBs detected (42GB)
   
⚙️  Automatically reducing parallelism: 2 → 1 (sequential)
💡 Reason: Large objects require exclusive lock table access
```

### 4. **Disk Space Warnings**

**Problem**: Backup fails silently when disk is full.

**Solutions**:
- 🔄 **NEW**: Pre-flight check before backup:
  ```
  📊 Disk Space Check:
     Database size: 42GB
     Available space: 66GB
     Estimated backup: ~15GB (compressed)
     ✓ Sufficient space available
  ```
- 🔄 **NEW**: Warning at 80% disk usage
- 🔄 **NEW**: Block operation at 95% disk usage

### 5. **Cancellation Handling (Ctrl+C)**

**Problem**: Users don't know if Ctrl+C will work or leave partial backups.

**Solutions**:
- ✅ Graceful cancellation on Ctrl+C
- 🔄 **NEW**: Show cleanup message:
  ```
  ^C received - Cancelling backup...
  🧹 Cleaning up temporary files...
  ✓ Cleanup complete - no partial backups left
  ```
- 🔄 **NEW**: Confirmation prompt for cluster operations:
  ```
  ⚠️  Cluster backup in progress (3/10 databases)
  Are you sure you want to cancel? (y/N)
  ```

### 6. **Interactive Mode Navigation**

**Problem**: TUI menu is basic, no keyboard shortcuts, no search.

**Solutions**:
- 🔄 **NEW**: Keyboard shortcuts:
  - `1-9`: Quick jump to menu items
  - `q`: Quit
  - `r`: Refresh status
  - `/`: Search backups
- 🔄 **NEW**: Backup list improvements:
  ```
  📦 Available Backups:
  
  1. cluster_20251118_103045.tar.gz  [45GB]  ⏱ 2 hours ago
     ├─ postgres (325MB)
     ├─ d7030 (42GB) ⚠️ 35K BLOBs
     └─ template1 (8MB)
  
  2. cluster_20251112_084329.tar.gz  [38GB]  ⏱ 6 days ago
     └─ ⚠️ WARNING: May contain corrupted resydb dump
  ```
- 🔄 **NEW**: Filter/sort options: by date, by size, by status

### 7. **Configuration Recommendations**

**Problem**: Users don't know optimal settings for their workload.

**Solutions**:
- 🔄 **NEW**: Auto-detect and suggest settings on first run:
  ```
  🔧 System Configuration Detected:
     RAM: 32GB → Recommended: shared_buffers=8GB
     CPUs: 4 cores → Recommended: parallel_jobs=3
     Disk: 66GB free → Recommended: max backup size: 50GB
     
  Apply these settings? (Y/n)
  ```
- 🔄 **NEW**: Show current vs recommended config in menu:
  ```
  ⚙️  Configuration Status:
     max_locks_per_transaction: 256 ✓ (sufficient for 35K objects)
     maintenance_work_mem: 64MB ⚠️ (recommend: 1GB for faster restores)
     shared_buffers: 128MB ⚠️ (recommend: 8GB with 32GB RAM)
  ```

### 8. **Backup Verification & Health**

**Problem**: No way to verify backup integrity before restore.

**Solutions**:
- 🔄 **NEW**: Add "Verify Backup" menu option:
  ```
  🔍 Verifying backup: cluster_20251118_103045.tar.gz
     ✓ Archive integrity: OK
     ✓ Extracting metadata...
     ✓ Checking dump formats...
     
  Databases found:
     ✓ postgres: Custom format, 325MB
     ✓ d7030: Custom format, 42GB, 35,000 BLOBs
     ⚠️  resydb: CORRUPTED - 2.5M syntax errors detected
     
  Overall: ⚠️ Partial (2/3 databases healthy)
  ```
- 🔄 **NEW**: Show last backup status in main menu

### 9. **Restore Dry Run**

**Problem**: No preview of what will be restored.

**Solution**:
```
🎬 Restore Preview (Dry Run):

Target: cluster_20251118_103045.tar.gz
Databases to restore:
  1. postgres (325MB)
     - Will overwrite: 5 existing objects
     - New objects: 120
     
  2. d7030 (42GB, 35K BLOBs)
     - Will DROP and recreate database
     - Estimated time: 25-30 minutes
     - Required locks: 35,000 (available: 25,600) ⚠️
     
⚠️  WARNING: Insufficient locks for d7030
💡 Solution: Increase max_locks_per_transaction to 512

Proceed with restore? (y/N)
```

### 10. **Multi-Step Wizards**

**Problem**: Complex operations (like cluster restore with --clean) need multiple confirmations.

**Solution**: Step-by-step wizard:
```
Step 1/4: Select backup
Step 2/4: Review databases to restore
Step 3/4: Check prerequisites (disk space, locks, etc.)
Step 4/4: Confirm and execute
```

## Implementation Priority

### Phase 1 (High Impact, Low Effort) ✅
- ✅ ETA estimators
- ✅ Large object detection warnings
- ✅ Ctrl+C handling
- ✅ Ignorable error detection

### Phase 2 (High Impact, Medium Effort) 🔄
- Real-time progress bars with MB/s
- Disk space pre-flight checks
- Backup verification tool
- Error hints and suggestions

### Phase 3 (Quality of Life) 🔄
- Keyboard shortcuts
- Backup list with metadata
- Configuration recommendations
- Restore dry run

### Phase 4 (Advanced) 📋
- Multi-step wizards
- Search/filter backups
- Auto-retry failed databases
- Parallel restore progress split-view

## Code Structure

```
internal/tui/
  menu.go          - Main interactive menu
  backup_menu.go   - Backup wizard
  restore_menu.go  - Restore wizard
  verify_menu.go   - Backup verification (NEW)
  config_menu.go   - Configuration tuning (NEW)
  progress_view.go - Real-time progress display (ENHANCED)
  errors.go        - Error classification & hints (NEW)
```

## Testing Plan

1. **Large Database Test** (In Progress)
   - 42GB d7030 with 35K BLOBs
   - Verify progress updates
   - Verify large object detection
   - Verify successful restore

2. **Error Scenarios**
   - Corrupted dump file
   - Insufficient disk space
   - Insufficient locks
   - Network interruption
   - Ctrl+C during operations

3. **Performance**
   - Backup time vs raw pg_dump
   - Restore time vs raw pg_restore
   - Memory usage during 40GB+ operations
   - CPU utilization with parallel workers

## Success Metrics

- ✅ No "black box" operations - user always knows what's happening
- ✅ Errors are actionable - user knows what to fix
- ✅ Safe operations - confirmations for destructive actions
- ✅ Fast feedback - progress updates every 1-2 seconds
- ✅ Professional feel - polished, consistent, intuitive