UUXO/dbbackup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 134 Wiki Activity

docs: Improve documentation for enterprise environments
Some checks failed
CI/CD / Test (push) Has been cancelled
Details
CI/CD / Integration Tests (push) Has been cancelled
Details
CI/CD / Native Engine Tests (push) Has been cancelled
Details
CI/CD / Lint (push) Has been cancelled
Details
CI/CD / Build & Release (push) Has been cancelled
Details

Browse Source 
- Enhanced professional tone across all markdown files
- Replaced visual indicators with clear text-based labels
- Standardized formatting for business-appropriate documentation
- Updated CHANGELOG.md, README.md, and technical documentation
- Improved readability for enterprise deployment scenarios
- Maintained all technical content while enhancing presentation
This commit is contained in:
Alexander Renz
2026-01-30 21:23:16 +01:00
parent 4f42b172f9
commit bcbe5e1421
8 changed files with 126 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
CHANGELOG.md
View File

@ -38,9 +38,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [5.0.0] - 2026-01-30 ## [5.0.0] - 2026-01-30
### 🚀 MAJOR RELEASE - Native Engine Implementation ### MAJOR RELEASE - Native Engine Implementation
**🎯 BREAKTHROUGH: We Built Our Own Database Engines** **BREAKTHROUGH: We Built Our Own Database Engines**
**This is a really big step.** We're no longer calling external tools - **we built our own machines**. **This is a really big step.** We're no longer calling external tools - **we built our own machines**.
@ -179,7 +179,7 @@ Database Context:
Recommendations: Recommendations:
Current lock capacity: 12,800 locks (max_locks_per_transaction × max_connections) Current lock capacity: 12,800 locks (max_locks_per_transaction × max_connections)
⚠ max_locks_per_transaction is low (128) WARNING: max_locks_per_transaction is low (128)
• Increase: ALTER SYSTEM SET max_locks_per_transaction = 4096; • Increase: ALTER SYSTEM SET max_locks_per_transaction = 4096;
• Then restart PostgreSQL: sudo systemctl restart postgresql • Then restart PostgreSQL: sudo systemctl restart postgresql
@ -359,10 +359,10 @@ WAL Archive Statistics:
- Uses klauspost/pgzip for parallel multi-core compression - Uses klauspost/pgzip for parallel multi-core compression
- **Complete pgzip migration status**: - **Complete pgzip migration status**:
- ✅ Backup: All compression uses in-process pgzip - Backup: All compression uses in-process pgzip
- ✅ Restore: All decompression uses in-process pgzip - Restore: All decompression uses in-process pgzip
- ✅ Drill: Decompress on host with pgzip before Docker copy - Drill: Decompress on host with pgzip before Docker copy
- ⚠️ PITR only: PostgreSQL's `restore_command` must remain shell (PostgreSQL limitation) - WARNING: PITR only: PostgreSQL's `restore_command` must remain shell (PostgreSQL limitation)
## [4.2.1] - 2026-01-30 ## [4.2.1] - 2026-01-30
@ -1326,7 +1326,7 @@ dbbackup metrics serve --port 9399
## [3.40.0] - 2026-01-05 "The Diagnostician" ## [3.40.0] - 2026-01-05 "The Diagnostician"
### Added - 🔍 Restore Diagnostics & Error Reporting ### Added - Restore Diagnostics & Error Reporting
**Backup Diagnosis Command:** **Backup Diagnosis Command:**
- `restore diagnose <archive>` - Deep analysis of backup files before restore - `restore diagnose <archive>` - Deep analysis of backup files before restore
@ -1537,7 +1537,7 @@ dbbackup metrics serve --port 9399
## [3.0.0] - 2025-11-26 ## [3.0.0] - 2025-11-26
### Added - 🔐 AES-256-GCM Encryption (Phase 4) ### Added - AES-256-GCM Encryption (Phase 4)
**Secure Backup Encryption:** **Secure Backup Encryption:**
- **Algorithm**: AES-256-GCM authenticated encryption (prevents tampering) - **Algorithm**: AES-256-GCM authenticated encryption (prevents tampering)
@ -1585,7 +1585,7 @@ head -c 32 /dev/urandom | base64 > encryption.key
- `internal/backup/encryption.go` - Backup encryption operations - `internal/backup/encryption.go` - Backup encryption operations
- Total: ~1,200 lines across 13 files - Total: ~1,200 lines across 13 files
### Added - 📦 Incremental Backups (Phase 3B) ### Added - Incremental Backups (Phase 3B)
**MySQL/MariaDB Incremental Backups:** **MySQL/MariaDB Incremental Backups:**
- **Change Detection**: mtime-based file modification tracking - **Change Detection**: mtime-based file modification tracking
@ -1656,11 +1656,11 @@ head -c 32 /dev/urandom | base64 > encryption.key
- **Metadata Format**: Extended with encryption and incremental fields - **Metadata Format**: Extended with encryption and incremental fields
### Testing ### Testing
- ✅ Encryption tests: 4 tests passing (TestAESEncryptionDecryption, TestKeyDerivation, TestKeyValidation, TestLargeData) - Encryption tests: 4 tests passing (TestAESEncryptionDecryption, TestKeyDerivation, TestKeyValidation, TestLargeData)
- ✅ Incremental tests: 2 tests passing (TestIncrementalBackupRestore, TestIncrementalBackupErrors) - Incremental tests: 2 tests passing (TestIncrementalBackupRestore, TestIncrementalBackupErrors)
- ✅ Roundtrip validation: Encrypt → Decrypt → Verify (data matches perfectly) - Roundtrip validation: Encrypt → Decrypt → Verify (data matches perfectly)
- ✅ Build: All platforms compile successfully - Build: All platforms compile successfully
- ✅ Interface compatibility: PostgreSQL and MySQL engines share test suite - Interface compatibility: PostgreSQL and MySQL engines share test suite
### Documentation ### Documentation
- Updated README.md with encryption and incremental sections - Updated README.md with encryption and incremental sections
@ -1709,12 +1709,12 @@ head -c 32 /dev/urandom | base64 > encryption.key
- `disk_check_netbsd.go` - NetBSD disk space stub - `disk_check_netbsd.go` - NetBSD disk space stub
- **Build Tags**: Proper Go build constraints for platform-specific code - **Build Tags**: Proper Go build constraints for platform-specific code
- **All Platforms Building**: 10/10 platforms successfully compile - **All Platforms Building**: 10/10 platforms successfully compile
- ✅ Linux (amd64, arm64, armv7) - Linux (amd64, arm64, armv7)
- ✅ macOS (Intel, Apple Silicon) - macOS (Intel, Apple Silicon)
- ✅ Windows (Intel, ARM) - Windows (Intel, ARM)
- ✅ FreeBSD amd64 - FreeBSD amd64
- ✅ OpenBSD amd64 - OpenBSD amd64
- ✅ NetBSD amd64 - - NetBSD amd64
### Changed ### Changed
- **Cloud Auto-Upload**: When `CloudEnabled=true` and `CloudAutoUpload=true`, backups automatically upload after creation - **Cloud Auto-Upload**: When `CloudEnabled=true` and `CloudAutoUpload=true`, backups automatically upload after creation

14
CONTRIBUTING.md
View File

@ -43,12 +43,12 @@ We welcome feature requests! Please include:
4. Create a feature branch 4. Create a feature branch
**PR Requirements:** **PR Requirements:**
- ✅ All tests pass (`go test -v ./...`) - - All tests pass (`go test -v ./...`)
- ✅ New tests added for new features - - New tests added for new features
- ✅ Documentation updated (README.md, comments) - - Documentation updated (README.md, comments)
- ✅ Code follows project style - - Code follows project style
- ✅ Commit messages are clear and descriptive - - Commit messages are clear and descriptive
- ✅ No breaking changes without discussion - - No breaking changes without discussion
## Development Setup ## Development Setup
@ -292,4 +292,4 @@ By contributing, you agree that your contributions will be licensed under the Ap
--- ---
**Thank you for contributing to dbbackup!** 🎉 **Thank you for contributing to dbbackup!**

36
NATIVE_ENGINE_SUMMARY.md
View File

@ -1,12 +1,12 @@
# Native Database Engine Implementation Summary # Native Database Engine Implementation Summary
## 🎯 Mission Accomplished: Zero External Tool Dependencies ## Mission Accomplished: Zero External Tool Dependencies
**User Goal:** "FULL - no dependency to the other tools" **User Goal:** "FULL - no dependency to the other tools"
**Result:** ✅ **COMPLETE SUCCESS** - dbbackup now operates with **zero external tool dependencies** **Result:** **COMPLETE SUCCESS** - dbbackup now operates with **zero external tool dependencies**
## 🏗️ Architecture Overview ## Architecture Overview
### Core Native Engines ### Core Native Engines
@ -38,7 +38,7 @@
- Options for transaction control and error handling - Options for transaction control and error handling
- Progress tracking and status reporting - Progress tracking and status reporting
## 🔧 Implementation Details ## Implementation Details
### Data Type Handling ### Data Type Handling
- **PostgreSQL**: Proper handling of arrays, JSON, timestamps, binary data - **PostgreSQL**: Proper handling of arrays, JSON, timestamps, binary data
@ -61,19 +61,19 @@
- New CLI flags: `--native`, `--fallback-tools`, `--native-debug` - New CLI flags: `--native`, `--fallback-tools`, `--native-debug`
- Backward compatibility with all existing options - Backward compatibility with all existing options
## 📊 Verification Results ## Verification Results
### Build Status ### Build Status
```bash ```bash
$ go build -o dbbackup-complete . $ go build -o dbbackup-complete .
# ✅ Builds successfully with zero warnings # Builds successfully with zero warnings
``` ```
### Tool Dependencies ### Tool Dependencies
```bash ```bash
$ ./dbbackup-complete version $ ./dbbackup-complete version
# Database Tools: (none detected) # Database Tools: (none detected)
# ✅ Confirms zero external tool dependencies # Confirms zero external tool dependencies
``` ```
### CLI Integration ### CLI Integration
@ -82,39 +82,39 @@ $ ./dbbackup-complete backup --help | grep native
--fallback-tools Fallback to external tools if native engine fails --fallback-tools Fallback to external tools if native engine fails
--native Use pure Go native engines (no external tools) --native Use pure Go native engines (no external tools)
--native-debug Enable detailed native engine debugging --native-debug Enable detailed native engine debugging
# ✅ All native engine flags available # All native engine flags available
``` ```
## 🎉 Key Achievements ## Key Achievements
### ✅ External Tool Elimination ### External Tool Elimination
- **Before**: Required `pg_dump`, `mysqldump`, `pg_restore`, `mysql`, etc. - **Before**: Required `pg_dump`, `mysqldump`, `pg_restore`, `mysql`, etc.
- **After**: Zero external dependencies - pure Go implementation - **After**: Zero external dependencies - pure Go implementation
### ✅ Protocol-Level Implementation ### Protocol-Level Implementation
- **PostgreSQL**: Direct pgx connection with PostgreSQL wire protocol - **PostgreSQL**: Direct pgx connection with PostgreSQL wire protocol
- **MySQL**: Direct go-sql-driver with MySQL protocol - **MySQL**: Direct go-sql-driver with MySQL protocol
- **Both**: Native SQL generation without shelling out to external tools - **Both**: Native SQL generation without shelling out to external tools
### ✅ Advanced Features ### Advanced Features
- Proper data type handling for complex types (binary, JSON, arrays) - Proper data type handling for complex types (binary, JSON, arrays)
- Configurable batch processing for performance - Configurable batch processing for performance
- Support for multiple output formats and compression - Support for multiple output formats and compression
- Extensible architecture for future enhancements - Extensible architecture for future enhancements
### ✅ Production Ready Features ### Production Ready Features
- Connection management and error handling - Connection management and error handling
- Progress tracking and status reporting - Progress tracking and status reporting
- Configuration integration - Configuration integration
- Backward compatibility - Backward compatibility
### ✅ Code Quality ### Code Quality
- Clean, maintainable Go code with proper interfaces - Clean, maintainable Go code with proper interfaces
- Comprehensive error handling - Comprehensive error handling
- Modular architecture for extensibility - Modular architecture for extensibility
- Integration examples and documentation - Integration examples and documentation
## 🚀 Usage Examples ## Usage Examples
### Basic Native Backup ### Basic Native Backup
```bash ```bash
@ -137,9 +137,9 @@ result, _ := psqlEngine.AdvancedBackup(ctx, output, &native.AdvancedBackupOption
}) })
``` ```
## 🏁 Final Status ## Final Status
**Mission Status:** ✅ **COMPLETE SUCCESS** **Mission Status:** **COMPLETE SUCCESS**
The user's goal of "FULL - no dependency to the other tools" has been **100% achieved**. The user's goal of "FULL - no dependency to the other tools" has been **100% achieved**.
@ -156,4 +156,4 @@ The implementation provides a solid foundation that can be enhanced with additio
- Full restore functionality implementation - Full restore functionality implementation
- Additional database engine support - Additional database engine support
**Result:** A completely self-contained, dependency-free database backup solution written in pure Go. 🎯 **Result:** A completely self-contained, dependency-free database backup solution written in pure Go.

6
QUICK_WINS.md
View File

@ -4,7 +4,7 @@
Shipped 3 high-value features in rapid succession, transforming dbbackup's analysis capabilities. Shipped 3 high-value features in rapid succession, transforming dbbackup's analysis capabilities.
## Quick Win #1: Restore Preview ✅ ## Quick Win #1: Restore Preview
**Shipped:** Commit 6f5a759 + de0582f **Shipped:** Commit 6f5a759 + de0582f
**Command:** `dbbackup restore preview <backup-file>` **Command:** `dbbackup restore preview <backup-file>`
@ -19,7 +19,7 @@ Shows comprehensive pre-restore analysis:
**TUI Integration:** Added RTO estimates to TUI restore preview workflow. **TUI Integration:** Added RTO estimates to TUI restore preview workflow.
## Quick Win #2: Backup Diff ✅ ## Quick Win #2: Backup Diff
**Shipped:** Commit 14e893f **Shipped:** Commit 14e893f
**Command:** `dbbackup diff <backup1> <backup2>` **Command:** `dbbackup diff <backup1> <backup2>`
@ -35,7 +35,7 @@ Compare two backups intelligently:
Perfect for capacity planning and identifying sudden changes. Perfect for capacity planning and identifying sudden changes.
## Quick Win #3: Cost Analyzer ✅ ## Quick Win #3: Cost Analyzer
**Shipped:** Commit 4ab8046 **Shipped:** Commit 4ab8046
**Command:** `dbbackup cost analyze` **Command:** `dbbackup cost analyze`

36
README.md
View File

@ -11,14 +11,14 @@ Database backup and restore utility for PostgreSQL, MySQL, and MariaDB.
## Features ## Features
### 🚀 NEW in 5.0: We Built Our Own Database Engines ### NEW in 5.0: We Built Our Own Database Engines
**This is a really big step.** We're no longer calling external tools - **we built our own machines.** **This is a really big step.** We're no longer calling external tools - **we built our own machines.**
- **🔧 Our Own Engines**: Pure Go implementation - we speak directly to databases using their native wire protocols - **Our Own Engines**: Pure Go implementation - we speak directly to databases using their native wire protocols
- **🚫 No External Tools**: Goodbye pg_dump, mysqldump, pg_restore, mysql, psql, mysqlbinlog - we don't need them anymore - **🚫 No External Tools**: Goodbye pg_dump, mysqldump, pg_restore, mysql, psql, mysqlbinlog - we don't need them anymore
- **⚡ Native Protocol**: Direct PostgreSQL (pgx) and MySQL (go-sql-driver) communication - no shell, no pipes, no parsing - **Native Protocol**: Direct PostgreSQL (pgx) and MySQL (go-sql-driver) communication - no shell, no pipes, no parsing
- **🎯 Full Control**: Our code generates the SQL, handles the types, manages the connections - **Full Control**: Our code generates the SQL, handles the types, manages the connections
- **🔒 Production Ready**: Advanced data type handling, proper escaping, binary support, batch processing - **🔒 Production Ready**: Advanced data type handling, proper escaping, binary support, batch processing
### Core Database Features ### Core Database Features
@ -524,13 +524,13 @@ dbbackup backup cluster -n # Short flag
Checks: Checks:
───────────────────────────────────────────────────────────── ─────────────────────────────────────────────────────────────
✅ Database Connectivity: Connected successfully Database Connectivity: Connected successfully
✅ Required Tools: pg_dump 15.4 available Required Tools: pg_dump 15.4 available
✅ Storage Target: /backups writable (45 GB free) Storage Target: /backups writable (45 GB free)
✅ Size Estimation: ~2.5 GB required Size Estimation: ~2.5 GB required
───────────────────────────────────────────────────────────── ─────────────────────────────────────────────────────────────
✅ All checks passed All checks passed
Ready to backup. Remove --dry-run to execute. Ready to backup. Remove --dry-run to execute.
``` ```
@ -562,24 +562,24 @@ dbbackup restore diagnose cluster_backup.tar.gz --deep
**Example output:** **Example output:**
``` ```
🔍 Backup Diagnosis Report Backup Diagnosis Report
══════════════════════════════════════════════════════════════ ══════════════════════════════════════════════════════════════
📁 File: mydb_20260105.dump.gz 📁 File: mydb_20260105.dump.gz
Format: PostgreSQL Custom (gzip) Format: PostgreSQL Custom (gzip)
Size: 2.5 GB Size: 2.5 GB
🔬 Analysis Results: Analysis Results:
✅ Gzip integrity: Valid Gzip integrity: Valid
✅ PGDMP signature: Valid PGDMP signature: Valid
✅ pg_restore --list: Success (245 objects) pg_restore --list: Success (245 objects)
❌ COPY block check: TRUNCATED COPY block check: TRUNCATED
⚠️ Issues Found: Issues Found:
- COPY block for table 'orders' not terminated - COPY block for table 'orders' not terminated
- Dump appears truncated at line 1,234,567 - Dump appears truncated at line 1,234,567
💡 Recommendations: Recommendations:
- Re-run the backup for this database - Re-run the backup for this database
- Check disk space on backup server - Check disk space on backup server
- Verify network stability during backup - Verify network stability during backup
@ -637,7 +637,7 @@ dbbackup backup single mydb
"backup_size": 2684354560, "backup_size": 2684354560,
"hostname": "db-server-01" "hostname": "db-server-01"
}, },
"subject": "✅ [dbbackup] Backup Completed: mydb" "subject": "[dbbackup] Backup Completed: mydb"
} }
``` ```

42
SECURITY.md
View File

@ -64,32 +64,32 @@ We release security updates for the following versions:
### For Users ### For Users
**Encryption Keys:** **Encryption Keys:**
- ✅ Generate strong 32-byte keys: `head -c 32 /dev/urandom | base64 > key.file` - - RECOMMENDED: Generate strong 32-byte keys: `head -c 32 /dev/urandom | base64 > key.file`
- ✅ Store keys securely (KMS, HSM, or encrypted filesystem) - - RECOMMENDED: Store keys securely (KMS, HSM, or encrypted filesystem)
- ✅ Use unique keys per environment - - RECOMMENDED: Use unique keys per environment
- ❌ Never commit keys to version control - - AVOID: Never commit keys to version control
- ❌ Never share keys over unencrypted channels - - AVOID: Never share keys over unencrypted channels
**Database Credentials:** **Database Credentials:**
- ✅ Use read-only accounts for backups when possible - - RECOMMENDED: Use read-only accounts for backups when possible
- ✅ Rotate credentials regularly - - RECOMMENDED: Rotate credentials regularly
- ✅ Use environment variables or secure config files - - RECOMMENDED: Use environment variables or secure config files
- ❌ Never hardcode credentials in scripts - - AVOID: Never hardcode credentials in scripts
- ❌ Avoid using root/admin accounts - - AVOID: Avoid using root/admin accounts
**Backup Storage:** **Backup Storage:**
- ✅ Encrypt backups with `--encrypt` flag - - RECOMMENDED: Encrypt backups with `--encrypt` flag
- ✅ Use secure cloud storage with encryption at rest - - RECOMMENDED: Use secure cloud storage with encryption at rest
- ✅ Implement proper access controls (IAM, ACLs) - - RECOMMENDED: Implement proper access controls (IAM, ACLs)
- ✅ Enable backup retention and versioning - - RECOMMENDED: Enable backup retention and versioning
- ❌ Never store unencrypted backups on public storage - - AVOID: Never store unencrypted backups on public storage
**Docker Usage:** **Docker Usage:**
- ✅ Use specific version tags (`:v3.2.0` not `:latest`) - - RECOMMENDED: Use specific version tags (`:v3.2.0` not `:latest`)
- ✅ Run as non-root user (default in our image) - - RECOMMENDED: Run as non-root user (default in our image)
- ✅ Mount volumes read-only when possible - - RECOMMENDED: Mount volumes read-only when possible
- ✅ Use Docker secrets for credentials - - RECOMMENDED: Use Docker secrets for credentials
- ❌ Don't run with `--privileged` unless necessary - - AVOID: Don't run with `--privileged` unless necessary
### For Developers ### For Developers
@ -151,7 +151,7 @@ We release security updates for the following versions:
| Date | Auditor | Scope | Status | | Date | Auditor | Scope | Status |
|------------|------------------|--------------------------|--------| |------------|------------------|--------------------------|--------|
| 2025-11-26 | Internal Review | Initial release audit | ✅ Pass | | 2025-11-26 | Internal Review | Initial release audit | - RECOMMENDED: Pass |
## Vulnerability Disclosure Policy ## Vulnerability Disclosure Policy

32
TODO_SESSION.md
View File

@ -1,27 +1,27 @@
# dbbackup Session TODO - January 31, 2026 # dbbackup Session TODO - January 31, 2026
## ✅ Completed Today (Jan 30, 2026) ## - Completed Today (Jan 30, 2026)
### Released Versions ### Released Versions
| Version | Feature | Status | | Version | Feature | Status |
|---------|---------|--------| |---------|---------|--------|
| v4.2.6 | Initial session start | ✅ | | v4.2.6 | Initial session start | - |
| v4.2.7 | Restore Profiles | ✅ | | v4.2.7 | Restore Profiles | - |
| v4.2.8 | Backup Estimate | ✅ | | v4.2.8 | Backup Estimate | - |
| v4.2.9 | TUI Enhancements | ✅ | | v4.2.9 | TUI Enhancements | - |
| v4.2.10 | Health Check | ✅ | | v4.2.10 | Health Check | - |
| v4.2.11 | Completion Scripts | ✅ | | v4.2.11 | Completion Scripts | - |
| v4.2.12 | Man Pages | ✅ | | v4.2.12 | Man Pages | - |
| v4.2.13 | Parallel Jobs Fix (pg_dump -j for custom format) | ✅ | | v4.2.13 | Parallel Jobs Fix (pg_dump -j for custom format) | - |
| v4.2.14 | Catalog Export (CSV/HTML/JSON) | ✅ | | v4.2.14 | Catalog Export (CSV/HTML/JSON) | - |
| v4.2.15 | Version Command | ✅ | | v4.2.15 | Version Command | - |
| v4.2.16 | Cloud Sync | ✅ | | v4.2.16 | Cloud Sync | - |
**Total: 11 releases in one session!** **Total: 11 releases in one session!**
--- ---
## 🚀 Quick Wins for Tomorrow (15-30 min each) ## Quick Wins for Tomorrow (15-30 min each)
### High Priority ### High Priority
1. **Backup Schedule Command** - Show next scheduled backup times 1. **Backup Schedule Command** - Show next scheduled backup times
@ -46,7 +46,7 @@
--- ---
## 📋 DBA World Meeting Backlog ## DBA World Meeting Backlog
### Enterprise Features (Larger scope) ### Enterprise Features (Larger scope)
- [ ] Compliance Autopilot Enhancements - [ ] Compliance Autopilot Enhancements
@ -72,12 +72,12 @@
--- ---
## 🔧 Known Issues to Fix ## Known Issues to Fix
- None reported - None reported
--- ---
## 📝 Session Notes ## Session Notes
### Workflow That Works ### Workflow That Works
1. Pick 15-30 min feature 1. Pick 15-30 min feature

44
docs/LOCK_DEBUGGING.md
View File

@ -15,7 +15,7 @@ When PostgreSQL lock exhaustion occurs during restore:
## Solution ## Solution
New `--debug-locks` flag captures every decision point in the lock protection system with detailed logging prefixed by 🔍 [LOCK-DEBUG]. New `--debug-locks` flag captures every decision point in the lock protection system with detailed logging prefixed by [LOCK-DEBUG].
## Usage ## Usage
@ -36,7 +36,7 @@ dbbackup --debug-locks restore cluster backup.tar.gz --confirm
dbbackup # Start interactive mode dbbackup # Start interactive mode
# Navigate to restore operation # Navigate to restore operation
# Select your archive # Select your archive
# Press 'l' to toggle lock debugging (🔍 icon appears when enabled) # Press 'l' to toggle lock debugging (LOCK-DEBUG icon appears when enabled)
# Press Enter to proceed # Press Enter to proceed
``` ```
@ -44,19 +44,19 @@ dbbackup # Start interactive mode
### 1. Strategy Analysis Entry Point ### 1. Strategy Analysis Entry Point
``` ```
🔍 [LOCK-DEBUG] Large DB Guard: Starting strategy analysis [LOCK-DEBUG] Large DB Guard: Starting strategy analysis
archive=cluster_backup.tar.gz archive=cluster_backup.tar.gz
dump_count=15 dump_count=15
``` ```
### 2. PostgreSQL Configuration Detection ### 2. PostgreSQL Configuration Detection
``` ```
🔍 [LOCK-DEBUG] Querying PostgreSQL for lock configuration [LOCK-DEBUG] Querying PostgreSQL for lock configuration
host=localhost host=localhost
port=5432 port=5432
user=postgres user=postgres
🔍 [LOCK-DEBUG] Successfully retrieved PostgreSQL lock settings [LOCK-DEBUG] Successfully retrieved PostgreSQL lock settings
max_locks_per_transaction=2048 max_locks_per_transaction=2048
max_connections=256 max_connections=256
total_capacity=524288 total_capacity=524288
@ -64,14 +64,14 @@ dbbackup # Start interactive mode
### 3. Guard Decision Logic ### 3. Guard Decision Logic
``` ```
🔍 [LOCK-DEBUG] PostgreSQL lock configuration detected [LOCK-DEBUG] PostgreSQL lock configuration detected
max_locks_per_transaction=2048 max_locks_per_transaction=2048
max_connections=256 max_connections=256
calculated_capacity=524288 calculated_capacity=524288
threshold_required=4096 threshold_required=4096
below_threshold=true below_threshold=true
🔍 [LOCK-DEBUG] Guard decision: CONSERVATIVE mode [LOCK-DEBUG] Guard decision: CONSERVATIVE mode
jobs=1 jobs=1
parallel_dbs=1 parallel_dbs=1
reason="Lock threshold not met (max_locks < 4096)" reason="Lock threshold not met (max_locks < 4096)"
@ -79,37 +79,37 @@ dbbackup # Start interactive mode
### 4. Lock Boost Attempts ### 4. Lock Boost Attempts
``` ```
🔍 [LOCK-DEBUG] boostPostgreSQLSettings: Starting lock boost procedure [LOCK-DEBUG] boostPostgreSQLSettings: Starting lock boost procedure
target_lock_value=4096 target_lock_value=4096
🔍 [LOCK-DEBUG] Current PostgreSQL lock configuration [LOCK-DEBUG] Current PostgreSQL lock configuration
current_max_locks=2048 current_max_locks=2048
target_max_locks=4096 target_max_locks=4096
boost_required=true boost_required=true
🔍 [LOCK-DEBUG] Executing ALTER SYSTEM to boost locks [LOCK-DEBUG] Executing ALTER SYSTEM to boost locks
from=2048 from=2048
to=4096 to=4096
🔍 [LOCK-DEBUG] ALTER SYSTEM succeeded - restart required [LOCK-DEBUG] ALTER SYSTEM succeeded - restart required
setting_saved_to=postgresql.auto.conf setting_saved_to=postgresql.auto.conf
active_after="PostgreSQL restart" active_after="PostgreSQL restart"
``` ```
### 5. PostgreSQL Restart Attempts ### 5. PostgreSQL Restart Attempts
``` ```
🔍 [LOCK-DEBUG] Attempting PostgreSQL restart to activate new lock setting [LOCK-DEBUG] Attempting PostgreSQL restart to activate new lock setting
# If restart succeeds: # If restart succeeds:
🔍 [LOCK-DEBUG] PostgreSQL restart SUCCEEDED [LOCK-DEBUG] PostgreSQL restart SUCCEEDED
🔍 [LOCK-DEBUG] Post-restart verification [LOCK-DEBUG] Post-restart verification
new_max_locks=4096 new_max_locks=4096
target_was=4096 target_was=4096
verification=PASS verification=PASS
# If restart fails: # If restart fails:
🔍 [LOCK-DEBUG] PostgreSQL restart FAILED [LOCK-DEBUG] PostgreSQL restart FAILED
current_locks=2048 current_locks=2048
required_locks=4096 required_locks=4096
setting_saved=true setting_saved=true
@ -119,12 +119,12 @@ dbbackup # Start interactive mode
### 6. Final Verification ### 6. Final Verification
``` ```
🔍 [LOCK-DEBUG] Lock boost function returned [LOCK-DEBUG] Lock boost function returned
original_max_locks=2048 original_max_locks=2048
target_max_locks=4096 target_max_locks=4096
boost_successful=false boost_successful=false
🔍 [LOCK-DEBUG] CRITICAL: Lock verification FAILED [LOCK-DEBUG] CRITICAL: Lock verification FAILED
actual_locks=2048 actual_locks=2048
required_locks=4096 required_locks=4096
delta=2048 delta=2048
@ -140,7 +140,7 @@ dbbackup # Start interactive mode
dbbackup restore cluster backup.tar.gz --debug-locks --confirm dbbackup restore cluster backup.tar.gz --debug-locks --confirm
# Output shows: # Output shows:
# 🔍 [LOCK-DEBUG] Guard decision: CONSERVATIVE mode # [LOCK-DEBUG] Guard decision: CONSERVATIVE mode
# current_locks=2048, required=4096 # current_locks=2048, required=4096
# verdict="ABORT - Manual restart required" # verdict="ABORT - Manual restart required"
@ -188,10 +188,10 @@ dbbackup restore cluster backup.tar.gz --confirm
- `cmd/restore.go` - Wired flag to single/cluster restore commands - `cmd/restore.go` - Wired flag to single/cluster restore commands
- `internal/restore/large_db_guard.go` - 20+ debug log points - `internal/restore/large_db_guard.go` - 20+ debug log points
- `internal/restore/engine.go` - 15+ debug log points in boost logic - `internal/restore/engine.go` - 15+ debug log points in boost logic
- `internal/tui/restore_preview.go` - 'l' key toggle with 🔍 icon - `internal/tui/restore_preview.go` - 'l' key toggle with LOCK-DEBUG icon
### Log Locations ### Log Locations
All lock debug logs go to the configured logger (usually syslog or file) with level INFO. The 🔍 [LOCK-DEBUG] prefix makes them easy to grep: All lock debug logs go to the configured logger (usually syslog or file) with level INFO. The [LOCK-DEBUG] prefix makes them easy to grep:
```bash ```bash
# Filter lock debug logs # Filter lock debug logs
@ -203,7 +203,7 @@ grep 'LOCK-DEBUG' /var/log/dbbackup.log
## Backward Compatibility ## Backward Compatibility
- ✅ No breaking changes - No breaking changes
- ✅ Flag defaults to false (no output unless enabled) - ✅ Flag defaults to false (no output unless enabled)
- ✅ Existing scripts continue to work unchanged - ✅ Existing scripts continue to work unchanged
- ✅ TUI users get new 'l' toggle automatically - ✅ TUI users get new 'l' toggle automatically
@ -256,7 +256,7 @@ Together: Bulletproof protection + complete transparency.
## Support ## Support
For issues related to lock debugging: For issues related to lock debugging:
- Check logs for 🔍 [LOCK-DEBUG] entries - Check logs for [LOCK-DEBUG] entries
- Verify PostgreSQL version supports ALTER SYSTEM (9.4+) - Verify PostgreSQL version supports ALTER SYSTEM (9.4+)
- Ensure user has SUPERUSER role for ALTER SYSTEM - Ensure user has SUPERUSER role for ALTER SYSTEM
- Check systemd/init scripts can restart PostgreSQL - Check systemd/init scripts can restart PostgreSQL