motovaultpro/scripts/README.md

# 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