{"id":2030,"library":"flask-migrate","title":"Flask-Migrate","description":"Flask-Migrate is an extension for Flask applications that streamlines database migrations using SQLAlchemy and Alembic. It integrates Alembic's powerful migration capabilities with the Flask command-line interface, providing version control for your database schema. The library sees regular maintenance, with minor releases addressing bugs and improvements, and major versions released to ensure compatibility with newer Flask and SQLAlchemy versions.","status":"active","version":"4.1.0","language":"en","source_language":"en","source_url":"https://github.com/miguelgrinberg/flask-migrate","tags":["flask","sqlalchemy","alembic","database","migrations"],"install":[{"cmd":"pip install Flask-Migrate","lang":"bash","label":"Install Flask-Migrate"}],"dependencies":[{"reason":"Core web framework integration.","package":"Flask"},{"reason":"ORM integration for database interactions.","package":"Flask-SQLAlchemy"},{"reason":"Underlying database migration tool, configured by Flask-Migrate.","package":"Alembic","optional":false}],"imports":[{"symbol":"Migrate","correct":"from flask_migrate import Migrate"}],"quickstart":{"code":"import os\nfrom flask import Flask\nfrom flask_sqlalchemy import SQLAlchemy\nfrom flask_migrate import Migrate\n\n# Set FLASK_APP environment variable if not already set\nif not os.environ.get('FLASK_APP'):\n    os.environ['FLASK_APP'] = 'app.py' # Assuming this file is named app.py\n\napp = Flask(__name__)\napp.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db'\napp.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False\ndb = SQLAlchemy(app)\nmigrate = Migrate(app, db)\n\nclass User(db.Model):\n    id = db.Column(db.Integer, primary_key=True)\n    name = db.Column(db.String(128))\n\n    def __repr__(self):\n        return f'<User {self.name}>'\n\n# To run this quickstart:\n# 1. Save as app.py\n# 2. In your terminal, ensure FLASK_APP is set (e.g., `export FLASK_APP=app.py` or `set FLASK_APP=app.py`)\n# 3. Run `flask db init` (creates migrations folder)\n# 4. Run `flask db migrate -m \"Initial migration\"` (creates migration script)\n# 5. Run `flask db upgrade` (applies migration to database)\n# 6. Now you can modify the User model, then repeat steps 4 and 5 to update your schema.","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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).","message":"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''.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions when using SQLite. Default behavior changed in 4.0.0."},{"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.","message":"Defining Flask app, SQLAlchemy db, and Flask-Migrate in the same file as models can lead to circular import issues, especially in larger applications.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}