# Deployment Migration Guide for Production Environment

## Recommended Procedure (Safe Approach)

### Pattern A: Fresh Clean Deployment (Recommended)

```bash
# 1. Create backup of old database
pg_dump rogaining_db > backup_$(date +%Y%m%d_%H%M%S).sql

# 2. Get latest code with Git pull
git pull origin main

# 3. Perform batch reset with migration_simple_reset.py (Recommended)
docker compose exec app python migration_simple_reset.py --full

# 4. Execute data restoration scripts if needed
# (When existing data is present)
```

### Pattern B: Gradual Migration Fix

```bash
# 1. Create backup of old database
pg_dump rogaining_db > backup_$(date +%Y%m%d_%H%M%S).sql

# 2. Get latest code with Git pull
git pull origin main

# 3. Temporarily remove problematic migration file
rm rog/migrations/0011_auto_20250827_1459.py

# 4. Apply migrations up to the last working one
docker compose exec app python manage.py migrate

# 5. Clean up with migration_simple_reset.py
docker compose exec app python migration_simple_reset.py --reset-only
docker compose exec app python migration_simple_reset.py --apply-only
```

## ⚠️ Issues with Original Proposed Procedure

```bash
1) Restore old DB ✅ OK
2) Git pull to deploy latest code ✅ OK  
3) Run migrate to update DB ❌ Problem: Will fail with dependency error
4) Execute migration_simple_reset.py ✅ OK
```

**Issue**: Step 3 will encounter `NodeNotFoundError` and migration will fail.

## Specific Deployment Procedure (Production Recommended)

### Pre-deployment Preparation
```bash
# Verify connection to production environment
docker compose ps

# Check current migration status
docker compose exec app python manage.py showmigrations
```

### Execution Steps

#### Step 1: Create Backups
```bash
# Database backup
docker compose exec postgres-db pg_dump -U admin rogaining_db > deploy_backup_$(date +%Y%m%d_%H%M%S).sql

# Current migration files backup
cp -r rog/migrations rog/migrations_backup_deploy_$(date +%Y%m%d_%H%M%S)
```

#### Step 2: Code Update
```bash
# Get latest code
git pull origin main

# Verify migration_simple_reset.py exists
ls -la migration_simple_reset.py
```

#### Step 3: Execute Migration Reset
```bash
# Complete reset (recommended)
docker compose exec app python migration_simple_reset.py --full
```

Or step-by-step execution:
```bash
# Backup only
docker compose exec app python migration_simple_reset.py --backup-only

# Reset only
docker compose exec app python migration_simple_reset.py --reset-only

# Apply only
docker compose exec app python migration_simple_reset.py --apply-only
```

#### Step 4: Verify Results
```bash
# Check migration status
docker compose exec app python manage.py showmigrations

# Verify application functionality
docker compose exec app python manage.py check
```

#### Step 5: Restart Services
```bash
# Restart application
docker compose restart app

# Restart all services (if needed)
docker compose restart
```

## Troubleshooting

### Migration Failure Recovery

```bash
# 1. Clean up with migration_simple_reset.py
docker compose exec app python migration_simple_reset.py --reset-only

# 2. Manually check migration status
docker compose exec app python manage.py showmigrations

# 3. Apply individual migrations if needed
docker compose exec app python manage.py migrate rog 0001 --fake
```

### Restore from Backup

```bash
# Database restoration
docker compose exec postgres-db psql -U admin -d rogaining_db < backup_file.sql

# Migration files restoration
rm -rf rog/migrations
cp -r rog/migrations_backup_deploy_YYYYMMDD_HHMMSS rog/migrations
```

## Important Considerations

### ✅ Pre-execution Checklist
- [ ] Database backup created
- [ ] Migration files backup created
- [ ] migration_simple_reset.py is latest version
- [ ] Docker environment running normally
- [ ] Sufficient disk space available

### ⚠️ Operations to Avoid
- Running `python manage.py migrate` first (causes dependency errors)
- Working without backups
- Experimental operations in production environment

### 🔄 Rollback Plan
```bash
# Emergency restoration when issues occur
docker compose down
docker compose exec postgres-db psql -U admin -d rogaining_db < backup_file.sql
cp -r rog/migrations_backup_deploy_YYYYMMDD_HHMMSS rog/migrations
docker compose up -d
```

## Summary

**Recommended Final Procedure:**

```bash
# 1. Create backup
pg_dump rogaining_db > backup_$(date +%Y%m%d_%H%M%S).sql

# 2. Get latest code
git pull origin main

# 3. Batch migration reset (avoids issues)
docker compose exec app python migration_simple_reset.py --full

# 4. Verify functionality
docker compose exec app python manage.py check
docker compose restart app
```

This procedure avoids migration dependency issues and enables safe deployment.

## Command Reference

### migration_simple_reset.py Options

```bash
# Complete workflow
python migration_simple_reset.py --full

# Backup only
python migration_simple_reset.py --backup-only

# Reset only (requires existing backup)
python migration_simple_reset.py --reset-only

# Apply only (requires simple migration to exist)
python migration_simple_reset.py --apply-only
```

### Docker Compose Commands

```bash
# Check service status
docker compose ps

# Execute commands in app container
docker compose exec app [command]

# Execute commands in database container
docker compose exec postgres-db [command]

# Restart specific service
docker compose restart [service_name]

# View logs
docker compose logs [service_name]
```

### Database Operations

```bash
# Create database backup
docker compose exec postgres-db pg_dump -U admin rogaining_db > backup.sql

# Restore database
docker compose exec postgres-db psql -U admin -d rogaining_db < backup.sql

# Connect to database shell
docker compose exec postgres-db psql -U admin -d rogaining_db
```

## Error Scenarios and Solutions

### Scenario 1: Migration Dependency Error
**Error**: `NodeNotFoundError: Migration rog.0010_auto_20250827_1510 dependencies reference nonexistent parent node`

**Solution**:
```bash
docker compose exec app python migration_simple_reset.py --full
```

### Scenario 2: Database Connection Error
**Error**: Database connection issues during migration

**Solution**:
```bash
# Check database status
docker compose ps postgres-db

# Restart database if needed
docker compose restart postgres-db

# Wait for database to be ready
docker compose exec postgres-db pg_isready -U admin
```

### Scenario 3: Disk Space Issues
**Error**: Insufficient disk space during backup or migration

**Solution**:
```bash
# Check disk usage
df -h

# Clean up Docker resources
docker system prune

# Remove old backups if safe
rm old_backup_files.sql
```

### Scenario 4: Permission Issues
**Error**: Permission denied when executing scripts

**Solution**:
```bash
# Make script executable
chmod +x migration_simple_reset.py

# Check file ownership
ls -la migration_simple_reset.py

# Fix ownership if needed
chown user:group migration_simple_reset.py
```

## Best Practices

### 1. Always Create Backups
- Database backup before any migration operation
- Migration files backup for rollback capability
- Configuration files backup

### 2. Test in Staging Environment
- Verify the migration procedure in staging first
- Test with production-like data volume
- Validate application functionality after migration

### 3. Monitor During Deployment
- Watch container logs during migration
- Monitor database performance
- Check application health endpoints

### 4. Document Changes
- Record migration procedure execution
- Note any deviations from standard procedure
- Update deployment documentation

### 5. Plan for Rollback
- Have clear rollback procedures ready
- Test rollback in staging environment
- Ensure backups are valid and accessible

This guide ensures safe and reliable deployment of the rogaining_srv application with proper migration handling.