{"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":"python","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,"search_vec":"'address':50 'alemb':20,23,69 'applic':12 'bug':51 'capabl':27 'command':32 'command-lin':31 'compat':60 'control':37 'databas':15,40,70 'ensur':59 'extens':9 'flask':2,5,11,30,63,67 'flask-migr':1,4 'improv':53 'integr':22 'interfac':34 'librari':43 'line':33 'mainten':46 'major':55 'migrat':3,6,16,26,71 'minor':48 'newer':62 'power':25 'provid':35 'regular':45 'releas':49,57 'schema':41 'see':44 'sqlalchemi':18,65,68 'streamlin':14 'use':17 'version':36,56,66","created_at":"2026-04-09T18:40:31.330568+00:00","updated_at":"2026-04-16T15:07:21.083663+00:00","problems":[{"fix":"Ensure Flask-Migrate is installed using pip: `pip install Flask-Migrate`. If using a virtual environment, make sure it's activated before installation.","cause":"The `flask_migrate` package is not installed in the current Python environment or the environment where the Flask application is being run.","error":"ModuleNotFoundError: No module named 'flask_migrate'"},{"fix":"Ensure `Migrate` is initialized correctly in your Flask application (e.g., `migrate = Migrate(app, db)`). Also, verify that the `FLASK_APP` environment variable is set to the correct entry point for your Flask application (e.g., `export FLASK_APP=your_app_name.py`).","cause":"The Flask `db` command group, provided by Flask-Migrate, is not registered with the Flask application. This often happens when `Migrate` is not properly initialized with the Flask app and SQLAlchemy `db` object, or when the `FLASK_APP` environment variable is not correctly set to point to your application instance.","error":"Error: No such command 'db'"},{"fix":"Ensure operations that require the application context (like initializing `Migrate` or `SQLAlchemy`) are done within an active application context. For CLI commands, ensure `FLASK_APP` is set. For programmatic access outside of a request, use `with app.app_context():` to establish a context.","cause":"This error occurs when `flask-migrate` or `SQLAlchemy` operations requiring an active Flask application context are called outside of one, typically in scripts or at the module level before the application context has been pushed.","error":"RuntimeError: Working outside of application context."},{"fix":"Ensure all your SQLAlchemy models are imported within your `env.py` file or in a module that `env.py` imports. Sometimes, simply adding `import app.models` (or your specific models package) in `env.py` after `target_metadata` is defined can resolve this. Also, verify that changes are truly present and not already applied to the database by manually checking the database schema.","cause":"Alembic (used by Flask-Migrate) may not detect changes to your SQLAlchemy models if the models are not properly imported into the environment where migrations are generated (e.g., `migrations/env.py`), or if the database schema already matches the models.","error":"Flask-Migrate not detecting model changes (generates empty migration script)"},{"fix":"Check the compatibility matrix for Flask-Migrate and SQLAlchemy versions. Upgrading or downgrading SQLAlchemy to a compatible version often resolves this. For instance, `pip install 'SQLAlchemy<1.4'` was a common fix for certain `AttributeError` issues. Review your model definitions for any unusual attribute assignments.","cause":"This error often indicates an incompatibility between Flask-Migrate and the installed version of SQLAlchemy, or sometimes an issue with how models are defined (e.g., trying to set a read-only attribute). Specific cases like 'AttributeError: module 'sqlalchemy' has no attribute 'Variant'' are common with older SQLAlchemy versions not compatible with newer Flask-Migrate.","error":"AttributeError: can't set attribute"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.1.0","cli_name":"flask","cli_version":"Python 3.11.15","type":"library","homepage":"https://flask-migrate.readthedocs.org","github":"https://github.com/miguelgrinberg/flask-migrate","docs":null,"changelog":null,"pypi":"https://pypi.org/project/flask-migrate/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","database","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}