rogaining_srv/DEPLOYMENT_MIGRATION_GUIDE_en.md

Deployment Migration Guide for Production Environment

Recommended Procedure (Safe Approach)

Pattern A: Fresh Clean Deployment (Recommended)

# 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

# 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

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

# 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

# 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

# Get latest code
git pull origin main

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

Step 3: Execute Migration Reset

# Complete reset (recommended)
docker compose exec app python migration_simple_reset.py --full

Or step-by-step execution:

# 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

# 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

# Restart application
docker compose restart app

# Restart all services (if needed)
docker compose restart

Troubleshooting

Migration Failure Recovery

# 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

# 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

# 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:

# 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

# 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

# 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

# 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:

docker compose exec app python migration_simple_reset.py --full

Scenario 2: Database Connection Error

Error: Database connection issues during migration

Solution:

# 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:

# 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:

# 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.