Database Tooling

scripts/README.md

@@ -0,0 +1,240 @@
+# MotoVaultPro Scripts
+
+Utility scripts for database management and operations.
+
+## Database Export/Import Scripts
+
+### Quick Start
+
+```bash
+# Export full database
+make db-export
+
+# Export schema only
+make db-export-schema
+
+# Create timestamped backup
+make db-backup
+
+# Import from file
+make db-import-file FILE=database-exports/backup.sql.gz
+```
+
+### Available Scripts
+
+#### `export-database.sh`
+Exports PostgreSQL database in multiple formats with metadata and instructions.
+
+**Features:**
+- Multiple export formats (SQL, custom, directory)
+- Automatic compression
+- Schema-only or data-only exports
+- Table filtering
+- Generates import instructions
+
+**Usage:**
+```bash
+# Full export
+./scripts/export-database.sh
+
+# Schema only
+./scripts/export-database.sh --schema-only
+
+# Custom format (faster for large databases)
+./scripts/export-database.sh --format custom
+
+# Specific tables
+./scripts/export-database.sh --include-table vehicles --include-table fuel_logs
+
+# Exclude tables
+./scripts/export-database.sh --exclude-table audit_logs
+```
+
+#### `import-database.sh`
+Imports PostgreSQL database with safety features and validation.
+
+**Features:**
+- Auto-detects export format
+- Automatic backup before import
+- Safety confirmations
+- Database creation
+- Import verification
+
+**Usage:**
+```bash
+# Basic import
+./scripts/import-database.sh database-exports/backup.sql.gz
+
+# Create new database
+./scripts/import-database.sh --create-db backup.sql.gz
+
+# Replace existing (with confirmation)
+./scripts/import-database.sh --drop-existing backup.sql.gz
+
+# Automated import (no prompts)
+./scripts/import-database.sh --drop-existing --force backup.sql.gz
+```
+
+### Makefile Shortcuts
+
+```bash
+# Export Commands
+make db-export          # Full database export
+make db-export-schema   # Schema only with date
+make db-export-custom   # Custom format with date
+make db-backup          # Timestamped backup
+
+# Import Commands
+make db-import          # Show import help
+make db-import-file FILE=path/to/backup.sql.gz
+```
+
+### Output Files
+
+Each export creates three files:
+
+1. **Export file** (`.sql.gz`, `.dump`, or directory)
+   - The actual database dump
+
+2. **Metadata file** (`*_metadata.json`)
+   - Export timestamp, format, size
+   - PostgreSQL version
+   - Export options used
+
+3. **Import instructions** (`*_import_instructions.txt`)
+   - Step-by-step import guide
+   - Format-specific commands
+   - Database preparation steps
+
+### Common Use Cases
+
+#### Production Backup
+```bash
+# Daily backup with timestamp
+make db-backup
+
+# Result: database-exports/backup_20251102_143000.sql.gz
+```
+
+#### Development Setup
+```bash
+# Get schema from production
+ssh prod "cd /app && ./scripts/export-database.sh --schema-only --output dev_schema"
+scp prod:/app/database-exports/dev_schema.sql.gz ./database-exports/
+
+# Import to dev
+./scripts/import-database.sh --create-db database-exports/dev_schema.sql.gz
+```
+
+#### Migration Between Servers
+```bash
+# On source server
+./scripts/export-database.sh --format custom --output migration_$(date +%Y%m%d)
+
+# Transfer to target
+scp database-exports/migration_* target:/app/database-exports/
+
+# On target server
+./scripts/import-database.sh --drop-existing database-exports/migration_20251102.dump
+```
+
+#### Selective Data Export
+```bash
+# Export only vehicle-related data
+./scripts/export-database.sh \
+  --include-table vehicles \
+  --include-table fuel_logs \
+  --include-table maintenance_records \
+  --output vehicle_data
+```
+
+### Safety Features
+
+#### Automatic Backups
+Before destructive operations, the import script automatically creates a backup:
+```
+[INFO] Creating backup: database-exports/motovaultpro_backup_20251102_143000.sql.gz
+[INFO] Backup created successfully
+```
+
+#### Confirmation Prompts
+Dangerous operations require explicit confirmation:
+```
+WARNING: This will DROP the existing database 'motovaultpro'
+All data will be permanently deleted!
+
+Are you sure you want to continue? (type 'yes' to confirm):
+```
+
+#### Format Validation
+Scripts detect and validate file formats automatically:
+```
+[INFO] Auto-detected format: sql-compressed
+```
+
+### Troubleshooting
+
+#### Container Not Running
+```bash
+Error: PostgreSQL container 'mvp-postgres' is not running
+
+Solution:
+docker compose up -d mvp-postgres
+```
+
+#### Permission Issues
+```bash
+chmod +x scripts/export-database.sh
+chmod +x scripts/import-database.sh
+```
+
+#### Large Database Exports
+For databases >1GB, use custom format:
+```bash
+./scripts/export-database.sh --format custom --no-compress
+```
+
+### Advanced Usage
+
+#### Automated Backups with Cron
+```bash
+# Daily at 2 AM
+0 2 * * * cd /app && ./scripts/export-database.sh --output daily_$(date +%Y%m%d) >> /var/log/db-backup.log 2>&1
+
+# Weekly on Sunday at 3 AM
+0 3 * * 0 cd /app && ./scripts/export-database.sh --format custom --output weekly_$(date +%Y%m%d) >> /var/log/db-backup.log 2>&1
+```
+
+#### Cleanup Old Backups
+```bash
+# Keep last 7 days of daily backups
+find database-exports/ -name "daily_*.sql.gz" -mtime +7 -delete
+
+# Keep last 4 weeks of weekly backups
+find database-exports/ -name "weekly_*.dump" -mtime +28 -delete
+```
+
+#### Export for Analysis
+```bash
+# Export specific tables for data analysis
+./scripts/export-database.sh \
+  --data-only \
+  --include-table fuel_logs \
+  --include-table maintenance_records \
+  --output analytics_data
+```
+
+## Documentation
+
+For detailed information, see:
+- [Database Migration Guide](../docs/DATABASE-MIGRATION.md) - Comprehensive migration documentation
+- [Architecture](../docs/ARCHITECTURE.md) - System architecture
+- [Platform Services](../docs/PLATFORM-SERVICES.md) - Service architecture
+
+## Support
+
+For issues:
+1. Check the import instructions file (`*_import_instructions.txt`)
+2. Review `docker logs mvp-postgres`
+3. See troubleshooting in [DATABASE-MIGRATION.md](../docs/DATABASE-MIGRATION.md)
+4. Create an issue in the repository