Database Migrations
A database migration is a versioned, repeatable change to your schema that transforms an existing database to match your updated models without losing data, and Flask-Migrate gives you simple commands to generate and apply them.
Learn Database Migrations in our free Flask course — a beginner-friendly interactive lesson with worked examples, a practice exercise and a quick reference.
Part of the free Flask course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.
In this lesson you'll set up Flask-Migrate, initialize a migration repository, and generate and apply your first migration with the flask db commands.
A migration is a versioned schema change . When you add a column to a model, the existing database still has the old shape. A migration records the exact change so the database can catch up without losing its rows.
db.create_all() only creates tables that do not yet exist — it never alters a table that is already there. To add a column to a populated table you need a migration that issues the right ALTER while preserving data.
You wire Flask-Migrate into your app by creating a Migrate object bound to both the app and the db . That one line unlocks the flask db command group.
With Migrate(app, db) in place, your terminal now understands commands like flask db init . The migration tooling runs from the command line, not from Python.
The workflow has three terminal commands. Run flask db init once to create a migrations/ folder. After that, every time you change a model you run flask db migrate to generate a script, then flask db upgrade to apply it.
The Python editor below shows the model change that would trigger a migration — adding an email column:
Complete the setup below. Replace each ___ so it imports and binds Flask-Migrate to a model with a new column.
Flask-Migrate is not active. Make sure you installed it with pip install flask-migrate and created Migrate(app, db) in your app file.
You generated a migration but never applied it. Run flask db upgrade to bring the database in line before generating more.
Plan the migration for adding a new column to an existing model.
Lesson 13 complete — your schema can evolve safely!
You set up Flask-Migrate and learned the init , migrate , and upgrade workflow. Your database can now change shape without losing data.
🚀 Up next: Error Handling & Custom Pages — turn ugly stack traces into friendly error pages.
Practice quiz
What is a database migration?
- A backup copy of the database
- A new web route
- A versioned schema change that updates the database without losing data
- A way to encrypt rows
Answer: A versioned schema change that updates the database without losing data. A migration is a versioned schema change that transforms an existing database safely.
Why isn't db.create_all() enough for an existing table?
- It only creates tables that don't exist; it never alters existing ones
- It deletes all data
- It only works on SQLite
- It requires Alembic
Answer: It only creates tables that don't exist; it never alters existing ones. create_all() makes missing tables but won't ALTER a table that already exists.
Flask-Migrate is a wrapper around which tool?
- SQLAlchemy
- Alembic
- Pytest
- Jinja2
Answer: Alembic. Flask-Migrate wraps Alembic and adds flask db commands.
How do you enable migrations in your app?
- Call db.migrate()
- Import alembic directly
- Set MIGRATE=True in config
- Create Migrate(app, db)
Answer: Create Migrate(app, db). migrate = Migrate(app, db) registers the flask db command group.
Which command creates the migrations/ folder (run once)?
- flask db init
- flask db create
- flask db start
- flask db new
Answer: flask db init. flask db init sets up the migrations/ directory one time.
Which command generates a migration script from model changes?
- flask db build
- flask db migrate
- flask db make
- flask db diff
Answer: flask db migrate. flask db migrate auto-generates a script from your model changes.
Which command applies pending migrations to the database?
- flask db apply
- flask db push
- flask db upgrade
- flask db commit
Answer: flask db upgrade. flask db upgrade applies the pending migrations.
Which command reverts the most recent migration?
- flask db revert
- flask db undo
- flask db rollback
- flask db downgrade
Answer: flask db downgrade. flask db downgrade rolls back the latest migration.
What benefit do migrations give a team?
- They speed up queries
- Everyone applies the same schema changes in order
- They remove the need for a database
- They auto-generate routes
Answer: Everyone applies the same schema changes in order. Versioned, numbered scripts let a whole team apply changes consistently.
What does 'Target database is not up to date' usually mean?
- The model has a syntax error
- You never created Migrate(app, db)
- You generated a migration but never ran flask db upgrade
- The database is corrupt
Answer: You generated a migration but never ran flask db upgrade. It means a pending migration hasn't been applied; run flask db upgrade.