TimeTrack/DEBUGGING_MIGRATIONS.md

Debugging Migration Issues in Docker

Quick Solutions

Container Exits Immediately

Use one of these approaches:

1. Debug Mode (Recommended)

   docker-compose down
   DEBUG_MODE=true docker-compose up
   

2. Skip Migrations Temporarily

   docker-compose down
   SKIP_MIGRATIONS=true docker-compose up
   

3. Use Debug Compose File

   docker-compose -f docker-compose.debug.yml up
   docker exec -it timetrack_web_1 bash
   

Debug Entrypoint

The debug_entrypoint.sh keeps the container running and provides diagnostic info:

# In docker-compose.yml, change:
command: ["./startup_postgres.sh"]
# To:
entrypoint: ["./debug_entrypoint.sh"]

# Then:
docker-compose up -d
docker exec -it <container_name> bash

Safe Startup Script

startup_postgres_safe.sh has three modes:

1. Normal Mode: Exits on migration failure (default)
2. Debug Mode: Continues running even if migrations fail

   DEBUG_MODE=true docker-compose up
   

3. Skip Mode: Skips migrations entirely

   SKIP_MIGRATIONS=true docker-compose up
   

Common Debugging Steps

1. Get Into the Container

# If container keeps exiting, use debug compose:
docker-compose -f docker-compose.debug.yml up -d web
docker exec -it timetrack_web_1 bash

# Or modify your docker-compose.yml:
# Add: stdin_open: true
# Add: tty: true
# Change: entrypoint: ["/bin/bash"]

2. Manual Migration Setup

# Inside container:
export FLASK_APP=app.py

# Check what's wrong
python diagnose_migrations.py

# Initialize migrations
python docker_migrate_init.py

# Fix revision issues
python fix_revision_mismatch.py

3. Database Connection Issues

# Test connection
python -c "from app import app, db; app.app_context().push(); db.engine.execute('SELECT 1')"

# Check environment
echo $DATABASE_URL
echo $POSTGRES_HOST

4. Reset Everything

# Inside container:
rm -rf migrations
python docker_migrate_init.py
flask db stamp head  # For existing DB
flask db upgrade     # For new DB

Docker Compose Examples

Development with Auto-Restart

services:
  web:
    environment:
      - DEBUG_MODE=true
    restart: unless-stopped  # Auto-restart on failure

Interactive Debugging

services:
  web:
    entrypoint: ["/app/debug_entrypoint.sh"]
    stdin_open: true
    tty: true

Skip Migrations for Testing

services:
  web:
    environment:
      - SKIP_MIGRATIONS=true

Environment Variables

• DEBUG_MODE=true - Continue running even if migrations fail
• SKIP_MIGRATIONS=true - Skip all migration steps
• FLASK_APP=app.py - Required for Flask-Migrate
• DATABASE_URL - PostgreSQL connection string

Step-by-Step Troubleshooting

1. Container won't start?

   # Use debug compose
   docker-compose -f docker-compose.debug.yml up
   

2. Migration fails?

   # Get into container
   docker exec -it <container> bash
   
   # Run diagnostics
   python diagnose_migrations.py
   

3. Revision mismatch?

   # Quick fix
   ./quick_fix_revision.sh
   
   # Or manual fix
   flask db stamp <revision>
   

4. Can't initialize migrations?

   # Check database connection first
   python -c "from app import app; print(app.config['SQLALCHEMY_DATABASE_URI'])"
   
   # Then initialize
   python docker_migrate_init.py
   

Tips

1. Always use volumes for migrations directory in development
2. Check logs carefully - the error is usually clear
3. Don't run migrations in production containers - include pre-tested migrations in image
4. Use DEBUG_MODE during development for easier troubleshooting
5. Test locally first before deploying to production

Recovery Commands

If everything is broken:

# 1. Start with debug entrypoint
docker-compose -f docker-compose.debug.yml up -d web

# 2. Get into container
docker exec -it timetrack_web_1 bash

# 3. Reset migrations
rm -rf migrations
python docker_migrate_init.py

# 4. Mark as current (existing DB) or create tables (new DB)
flask db stamp head  # Existing
flask db upgrade     # New

# 5. Test the app
python app.py  # Run in debug mode

# 6. If working, update docker-compose.yml and restart normally