Database Migrations (Flask-Migrate)

Migrations solve a dangerous problem:

• your models change over time
• your database schema must change too
• you need a safe, repeatable way to apply those changes

Flask-Migrate wraps Alembic to manage migrations.

diagram why create_all is not migrations mermaid

  flowchart TD
  A["you change a model"] --> B{"how is the schema updated?"}
  B -->|"db.create_all()"| C["existing tables are left ALONE"]
  C --> D["the new column never appears"]
  D --> E["OperationalError: no such column"]
  B -->|"Flask-Migrate"| F["flask db migrate -- autogenerate a script"]
  F --> G["read the script; autogenerate misses some changes"]
  G --> H["flask db upgrade -- apply it"]
  H --> I["the version is recorded in alembic_version"]
  I --> J["flask db downgrade can walk it back"]

create_all only creates tables that do not exist yet. It will never alter one that does, so the moment you add a column to a model that is already in the database, the two drift apart silently. Flask-Migrate records each change as a versioned script, so the database can be moved forward -- and back -- deliberately.

Install

bash

pip install Flask-Migrate

Setup

python

from flask_migrate import Migrate
 
migrate = Migrate(app, db)

Typical workflow

1. Initialize migrations folder:

bash

flask db init

2. Create a migration script:

bash

flask db migrate -m "create users table"

3. Apply it:

bash

flask db upgrade

Key idea

• migrate generates migration scripts from model diffs
• upgrade applies them to the database

Best practices

• review generated scripts before applying
• commit migrations to git
• run migrations in CI/staging before production