TimeTrack/FLASK_MIGRATE_TROUBLESHOOTING.md

Flask-Migrate Troubleshooting Guide

Common Issues and Solutions

0. Baseline Script Fails - "Could not extract models/"

Error: When running establish_baseline_4214e88.py:

⚠️ Could not extract models/__init__.py
⚠️ Could not extract models/base.py

Cause: Commit 4214e88 uses a single models.py file, not the modular models/ directory.

Solution:

# For local development with Git:
python simple_baseline_4214e88.py

# For Docker deployments (no Git):
python docker_migrate_init.py

1. "Target database is not up to date"

Error: When running flask db migrate, you get:

ERROR [flask_migrate] Target database is not up to date.

Solution:

# Apply pending migrations first
flask db upgrade

# Then create new migration
flask db migrate -m "Your changes"

2. "No changes in schema detected"

Possible Causes:

1. No actual model changes were made
2. Model not imported in models/__init__.py
3. Database already has the changes

Solutions:

# Check what Flask-Migrate sees
flask db compare

# Force detection by editing a model slightly
# (add a comment, save, then remove it)

# Check current state
python diagnose_migrations.py

3. After First Migration, Second One Fails

This is the most common issue!

After creating the baseline migration, you must apply it before creating new ones:

# Sequence:
flask db migrate -m "Initial migration"  # Works ✓
flask db migrate -m "Add new column"     # Fails ✗

# Fix:
flask db upgrade                         # Apply first migration
flask db migrate -m "Add new column"     # Now works ✓

4. Import Errors

Error: ModuleNotFoundError or ImportError

Solution:

# Ensure FLASK_APP is set
export FLASK_APP=app.py

# Check imports
python -c "from app import app, db; print('OK')"

5. PostgreSQL Enum Issues

Error: Cannot add new enum value in migration

Solution: Edit the generated migration file:

def upgrade():
    # Instead of using Enum type directly
    # Use raw SQL for PostgreSQL enums
    op.execute("ALTER TYPE taskstatus ADD VALUE IF NOT EXISTS 'NEW_VALUE'")

6. Migration Conflicts After Git Pull

Error: Conflicting migration heads

Solution:

# Merge the migrations
flask db merge -m "Merge migrations"

# Then upgrade
flask db upgrade

Quick Diagnostic Commands

# Run full diagnostics
python diagnose_migrations.py

# Fix sequence issues
python fix_migration_sequence.py

# Check current state
flask db current     # Current DB revision
flask db heads       # Latest file revision
flask db history     # All migrations

# Compare DB with models
flask db compare     # Shows differences

Best Practices to Avoid Issues

1. Always upgrade before new migrations:

   flask db upgrade
   flask db migrate -m "New changes"
   

2. Review generated migrations:

   • Check migrations/versions/ folder
   • Look for DROP commands you didn't intend

3. Test on development first:

   # Test the migration
   flask db upgrade
   
   # Test rollback
   flask db downgrade
   

4. Handle enums carefully:

   • PostgreSQL enums need special handling
   • Consider using String columns instead

5. Commit migrations with code:

   • Always commit migration files with model changes
   • This keeps database and code in sync

Revision Mismatch Errors

"Can't locate revision identified by 'xxxxx'"

This means your database thinks it's at a revision that doesn't exist in your migration files.

Quick Fix:

# Run the automated fix
./quick_fix_revision.sh

# Or manually:
# 1. Find your latest migration
ls migrations/versions/*.py

# 2. Get the revision from the file
grep "revision = " migrations/versions/latest_file.py

# 3. Stamp database to that revision
flask db stamp <revision_id>

Detailed Diagnosis:

python fix_revision_mismatch.py

Emergency Fixes

Reset Migration State (Development Only!)

# Remove migrations and start over
rm -rf migrations
python establish_baseline_4214e88.py
flask db stamp head

Force Database to Current State

# Mark database as up-to-date without running migrations
flask db stamp head

# Or stamp to specific revision
flask db stamp <revision_id>

Manual Migration Edit

Sometimes you need to edit the generated migration:

1. Generate migration: flask db migrate -m "Changes"
2. Edit file in migrations/versions/
3. Test with: flask db upgrade
4. Test rollback: flask db downgrade

Getting Help

If these solutions don't work:

1. Run diagnostics: python diagnose_migrations.py
2. Check the full error message
3. Look at the generated SQL: flask db upgrade --sql
4. Check Flask-Migrate logs in detail