Flask-Migrate

Warnings

• breaking Version 4.0.0 introduced significant changes, including compatibility updates for Flask-SQLAlchemy 3.x and automatically enabling `compare_type=True` and `render_as_batch=True` in Alembic by default. If you had custom Alembic configurations, especially for SQLite, you might need to review them.
  Fix: Review your application's `app.config['SQLALCHEMY_DATABASE_URI']` and any custom Alembic configurations. For SQLite, `render_as_batch=True` is now default, which should help with `ALTER TABLE` operations, but test thoroughly.
• gotcha The `flask db` commands rely on the `FLASK_APP` environment variable being correctly set to point to your Flask application instance (e.g., `app.py`). If this variable is not set or points to the wrong file, the commands will fail with 'No such command 'db''.
  Fix: Before running any `flask db` command, ensure `FLASK_APP` is set in your environment: `export FLASK_APP=your_app_file.py` (Linux/macOS) or `set FLASK_APP=your_app_file.py` (Windows).
• gotcha Alembic's autogenerate feature (used by `flask db migrate`) cannot detect all types of schema changes, such as table renames, column renames, changes to anonymously named constraints, or some index changes. The generated script is a best effort.
  Fix: Always review the generated migration script (`migrations/versions/*.py`) after running `flask db migrate`. Manually edit the `upgrade()` and `downgrade()` functions to correctly reflect any undetected changes before running `flask db upgrade`.
• gotcha SQLite has limited `ALTER TABLE` support. Operations like dropping or renaming columns directly are often not possible. Flask-Migrate (via Alembic) works around this using a 'batch mode' (`render_as_batch=True`) which copies data to a new table, drops the old, and renames the new.
  Fix: For versions < 4.0.0, explicitly set `render_as_batch=True` when initializing Migrate: `migrate = Migrate(app, db, render_as_batch=True)`. For all versions, be aware that complex SQLite schema changes might still require manual intervention in the migration script.
• gotcha Defining Flask app, SQLAlchemy db, and Flask-Migrate in the same file as models can lead to circular import issues, especially in larger applications.
  Fix: Structure your application to separate concerns: e.g., `app.py` for Flask app and `Migrate` initialization, `models.py` for SQLAlchemy models, and `config.py` for configuration. Import models into `app.py` *after* `db` is initialized to ensure they are registered with SQLAlchemy.

Install

• pip install Flask-Migrate Install Flask-Migrate

Imports

• Migrate

  from flask_migrate import Migrate

Quickstart

This example demonstrates the basic setup of Flask-Migrate with a Flask application and a SQLAlchemy model. It outlines the common commands to initialize a migration repository, create an initial migration script, and apply database changes.

import os
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate

# Set FLASK_APP environment variable if not already set
if not os.environ.get('FLASK_APP'):
    os.environ['FLASK_APP'] = 'app.py' # Assuming this file is named app.py

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db'
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
db = SQLAlchemy(app)
migrate = Migrate(app, db)

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(128))

    def __repr__(self):
        return f'<User {self.name}>'

# To run this quickstart:
# 1. Save as app.py
# 2. In your terminal, ensure FLASK_APP is set (e.g., `export FLASK_APP=app.py` or `set FLASK_APP=app.py`)
# 3. Run `flask db init` (creates migrations folder)
# 4. Run `flask db migrate -m "Initial migration"` (creates migration script)
# 5. Run `flask db upgrade` (applies migration to database)
# 6. Now you can modify the User model, then repeat steps 4 and 5 to update your schema.