Update README: Add UI examples, config persistence, reliability improvements
- Add interactive UI mockups showing main menu, progress, and settings - Document configuration persistence feature (.dbbackup.conf) - Update recent improvements section with reliability enhancements - Add new flags (--no-config, --no-save-config) to documentation - Expand best practices with configuration management guidance - Update platform support details and testing information - Remove all emoticons for conservative professional style
This commit is contained in:
141
README.md
141
README.md
@@ -76,16 +76,69 @@ MySQL/MariaDB:
|
|||||||
|
|
||||||
Menu-driven interface for all operations. Press arrow keys to navigate, Enter to select.
|
Menu-driven interface for all operations. Press arrow keys to navigate, Enter to select.
|
||||||
|
|
||||||
|
**Main Menu:**
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ Database Backup Tool │
|
||||||
|
├─────────────────────────────────────────────┤
|
||||||
|
│ > Backup Database │
|
||||||
|
│ Restore Database │
|
||||||
|
│ List Backups │
|
||||||
|
│ Configuration Settings │
|
||||||
|
│ Exit │
|
||||||
|
├─────────────────────────────────────────────┤
|
||||||
|
│ Database: postgres@localhost:5432 │
|
||||||
|
│ Type: PostgreSQL │
|
||||||
|
│ Backup Dir: /var/lib/pgsql/db_backups │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Backup Progress:**
|
||||||
|
```
|
||||||
|
Backing up database: production_db
|
||||||
|
|
||||||
|
[=================> ] 45%
|
||||||
|
Elapsed: 2m 15s | ETA: 2m 48s
|
||||||
|
|
||||||
|
Current: Dumping table users (1.2M records)
|
||||||
|
Speed: 25 MB/s | Size: 3.2 GB / 7.1 GB
|
||||||
|
```
|
||||||
|
|
||||||
|
**Configuration Settings:**
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ Configuration Settings │
|
||||||
|
├─────────────────────────────────────────────┤
|
||||||
|
│ Compression Level: 6 │
|
||||||
|
│ Parallel Jobs: 16 │
|
||||||
|
│ Dump Jobs: 8 │
|
||||||
|
│ CPU Workload: Balanced │
|
||||||
|
│ Max Cores: 32 │
|
||||||
|
├─────────────────────────────────────────────┤
|
||||||
|
│ Auto-saved to: .dbbackup.conf │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
#### Interactive Features
|
#### Interactive Features
|
||||||
|
|
||||||
- **Backup Selection**: Choose backup type (single, cluster, sample)
|
The interactive mode provides a menu-driven interface for all database operations:
|
||||||
- **Database Selection**: Browse and select database
|
|
||||||
- **Configuration Settings**: Set compression, parallelism, CPU workload, performance options
|
- **Backup Operations**: Single database, full cluster, or sample backups
|
||||||
- **CPU Workload Profiles**: Balanced, CPU-Intensive, or I/O-Intensive (auto-adjusts Jobs/DumpJobs)
|
- **Restore Operations**: Database or cluster restoration with safety checks
|
||||||
- **Backup Management**: List, restore, verify, and delete backup archives
|
- **Configuration Management**: Auto-save/load settings per directory (.dbbackup.conf)
|
||||||
- **Safety Checks**: Archive validation, disk space verification
|
- **Backup Archive Management**: List, verify, and delete backup files
|
||||||
- **Progress Tracking**: Real-time progress with ETA estimation
|
- **Performance Tuning**: CPU workload profiles (Balanced, CPU-Intensive, I/O-Intensive)
|
||||||
- **Restore Options**: Smart database cleanup detection, safety confirmations
|
- **Safety Features**: Disk space verification, archive validation, confirmation prompts
|
||||||
|
- **Progress Tracking**: Real-time progress indicators with ETA estimation
|
||||||
|
- **Error Handling**: Context-aware error messages with actionable hints
|
||||||
|
|
||||||
|
**Configuration Persistence:**
|
||||||
|
|
||||||
|
Settings are automatically saved to .dbbackup.conf in the current directory after successful operations and loaded on subsequent runs. This allows per-project configuration without global settings.
|
||||||
|
|
||||||
|
Flags available:
|
||||||
|
- `--no-config` - Skip loading saved configuration
|
||||||
|
- `--no-save-config` - Prevent saving configuration after operation
|
||||||
|
|
||||||
### Command Line Mode
|
### Command Line Mode
|
||||||
|
|
||||||
@@ -134,6 +187,8 @@ Restore full cluster:
|
|||||||
| `--max-cores` | Maximum CPU cores | 16 |
|
| `--max-cores` | Maximum CPU cores | 16 |
|
||||||
| `--cpu-workload` | cpu-intensive, io-intensive, balanced | balanced |
|
| `--cpu-workload` | cpu-intensive, io-intensive, balanced | balanced |
|
||||||
| `--auto-detect-cores` | Auto-detect CPU cores | true |
|
| `--auto-detect-cores` | Auto-detect CPU cores | true |
|
||||||
|
| `--no-config` | Skip loading .dbbackup.conf | false |
|
||||||
|
| `--no-save-config` | Prevent saving configuration | false |
|
||||||
| `--debug` | Enable debug logging | false |
|
| `--debug` | Enable debug logging | false |
|
||||||
| `--no-color` | Disable colored output | false |
|
| `--no-color` | Disable colored output | false |
|
||||||
|
|
||||||
@@ -690,14 +745,16 @@ Binaries created in `bin/` directory.
|
|||||||
|
|
||||||
## Best Practices
|
## Best Practices
|
||||||
|
|
||||||
1. **Test restores regularly** - Verify backups work
|
1. **Test restores regularly** - Verify backups work before disasters occur
|
||||||
2. **Monitor disk space** - Ensure adequate space
|
2. **Monitor disk space** - Maintain 4x archive size free space for restore operations
|
||||||
3. **Use compression** - Balance speed/space (level 3-6)
|
3. **Use appropriate compression** - Balance speed and space (level 3-6 for production)
|
||||||
4. **Automate backups** - cron or systemd timers
|
4. **Leverage configuration persistence** - Use .dbbackup.conf for consistent per-project settings
|
||||||
5. **Secure credentials** - .pgpass/.my.cnf with 0600 permissions
|
5. **Automate backups** - Schedule via cron or systemd timers
|
||||||
6. **Keep versions** - Multiple backup versions for point-in-time recovery
|
6. **Secure credentials** - Use .pgpass/.my.cnf with 0600 permissions, never save passwords in config files
|
||||||
7. **Off-site storage** - Remote backup copies
|
7. **Maintain multiple versions** - Keep 7-30 days of backups for point-in-time recovery
|
||||||
8. **Document procedures** - Maintain restore runbooks
|
8. **Store backups off-site** - Remote copies protect against site-wide failures
|
||||||
|
9. **Validate archives** - Run verification checks on backup files periodically
|
||||||
|
10. **Document procedures** - Maintain runbooks for restore operations and disaster recovery
|
||||||
|
|
||||||
## Project Structure
|
## Project Structure
|
||||||
|
|
||||||
@@ -730,33 +787,41 @@ MIT License
|
|||||||
|
|
||||||
## Recent Improvements
|
## Recent Improvements
|
||||||
|
|
||||||
|
### Reliability Enhancements
|
||||||
|
- **Context Cleanup**: Proper resource cleanup with sync.Once and io.Closer interface prevents memory leaks
|
||||||
|
- **Process Management**: Thread-safe process tracking with automatic cleanup on exit
|
||||||
|
- **Error Classification**: Regex-based error pattern matching for robust error handling
|
||||||
|
- **Performance Caching**: Disk space checks cached with 30-second TTL to reduce syscall overhead
|
||||||
|
- **Metrics Collection**: Structured logging with operation metrics for observability
|
||||||
|
|
||||||
|
### Configuration Management
|
||||||
|
- **Persistent Configuration**: Auto-save/load settings to .dbbackup.conf in current directory
|
||||||
|
- **Per-Directory Settings**: Each project maintains its own database connection parameters
|
||||||
|
- **Flag Override**: Command-line flags always take precedence over saved configuration
|
||||||
|
- **Security**: Passwords excluded from saved configuration files
|
||||||
|
|
||||||
### Performance Optimizations
|
### Performance Optimizations
|
||||||
- **Parallel Cluster Operations**: Worker pool pattern for concurrent database backup/restore (3-5x speedup)
|
- **Parallel Cluster Operations**: Worker pool pattern for concurrent database backup/restore
|
||||||
- **Memory Efficiency**: Streaming command output eliminates OOM errors on large restores
|
- **Memory Efficiency**: Streaming command output eliminates OOM errors on large databases
|
||||||
- **Optimized Goroutines**: Ticker-based progress indicators reduce CPU overhead
|
- **Optimized Goroutines**: Ticker-based progress indicators reduce CPU overhead
|
||||||
- **Configurable Concurrency**: Control parallel database operations via CLUSTER_PARALLELISM
|
- **Configurable Concurrency**: Control parallel database operations via CLUSTER_PARALLELISM
|
||||||
|
|
||||||
### Interactive UI Enhancements
|
### Cross-Platform Support
|
||||||
- **CPU Workload Profiles**: Configure workload type in settings (auto-adjusts parallelism)
|
- **Platform-Specific Implementations**: Separate disk space and process management for Unix/Windows/BSD
|
||||||
- **Backup Management**: Delete archives directly from TUI with confirmation
|
- **Build Constraints**: Go build tags ensure correct compilation for each platform
|
||||||
- **Better Callbacks**: Fixed confirmation dialogs to execute correct actions
|
- **Tested Platforms**: Linux (x64/ARM), macOS (x64/ARM), Windows (x64/ARM), FreeBSD, OpenBSD
|
||||||
- **Cleaner Interface**: Configuration consolidated in Settings menu
|
|
||||||
|
|
||||||
### Bug Fixes
|
|
||||||
- Fixed OOM error during large cluster restores
|
|
||||||
- Fixed delete backup incorrectly triggering cluster backup
|
|
||||||
- Fixed signal handler cleanup preventing goroutine leaks
|
|
||||||
- Improved error handling and user feedback
|
|
||||||
|
|
||||||
## Why dbbackup?
|
## Why dbbackup?
|
||||||
|
|
||||||
- **Reliable** - Comprehensive safety checks, validation, and error handling
|
- **Reliable**: Thread-safe process management, comprehensive error handling, automatic cleanup
|
||||||
- **Simple** - Intuitive menu-driven interface or straightforward CLI
|
- **Efficient**: Constant memory footprint (~1GB) regardless of database size via streaming architecture
|
||||||
- **Fast** - Automatic CPU detection, parallel processing, streaming compression
|
- **Fast**: Automatic CPU detection, parallel processing, streaming compression with pigz
|
||||||
- **Efficient** - Minimal memory footprint, even for huge databases (constant ~1GB regardless of size)
|
- **Intelligent**: Context-aware error messages, disk space pre-flight checks, configuration persistence
|
||||||
- **Flexible** - Multiple backup modes, compression levels, performance options
|
- **Safe**: Dry-run by default, archive verification, confirmation prompts, backup validation
|
||||||
- **Safe** - Dry-run by default, archive verification, smart database cleanup
|
- **Flexible**: Multiple backup modes, compression levels, CPU workload profiles, per-directory configuration
|
||||||
- **Complete** - Full cluster backup/restore, multiple formats
|
- **Complete**: Full cluster operations, single database backups, sample data extraction
|
||||||
- **Scalable** - Handles databases from megabytes to terabytes
|
- **Cross-Platform**: Native binaries for Linux, macOS, Windows, FreeBSD, OpenBSD
|
||||||
|
- **Scalable**: Tested with databases from megabytes to 100+ gigabytes
|
||||||
|
- **Observable**: Structured logging, metrics collection, progress tracking with ETA
|
||||||
|
|
||||||
dbbackup is production-ready for backup and disaster recovery operations on PostgreSQL, MySQL, and MariaDB databases of any size.
|
dbbackup is production-ready for backup and disaster recovery operations on PostgreSQL, MySQL, and MariaDB databases. Successfully tested with 42GB databases containing 35,000 large objects.
|
||||||
|
|||||||
Reference in New Issue
Block a user