Database Migrations with Flask-Migrate

db.create_all() is fine for a brand-new project because it only creates tables that don't yet exist — it never alters an existing table, so adding a column, renaming one, or changing a type on a live production database silently does nothing useful. Flask-Migrate solves this by wrapping Alembic, SQLAlchemy's migration toolkit, to generate versioned Python scripts that describe exactly how to transform the schema from one state to the next, and critically, how to reverse that transformation, giving you both upgrade() and downgrade() paths.

After installing Flask-Migrate and wiring Migrate(app, db) alongside your db object, running flask db init creates a migrations/ directory containing Alembic's configuration and an env.py that knows how to reach your models' metadata. From there, flask db migrate -m "add user table" inspects the difference between your current models and the database's tracked state to autogenerate a migration script, and flask db upgrade actually applies it, while flask db downgrade reverts the most recent migration.

In production, migrations should run as an explicit deployment step — typically flask db upgrade invoked once before the new application code starts serving traffic — rather than automatically inside app startup code, because running it from every worker process on every restart risks concurrent migration attempts racing against each other. For irreversible or risky changes, such as dropping a column that's still read by the previous app version during a rolling deploy, split the migration into multiple deploys: first add the new column and dual-write, then backfill data, then only in a later deploy drop the old column once nothing references it.