A Flask Extension to provide Alembic integration with Flask.
Switch branches/tags
Nothing to show
Latest commit d0f4d35 Feb 4, 2013 @eadmundo eadmundo Merge pull request #3 from r1s/patch-1
Update setup.py
Failed to load latest commit information.
flask_alembic moved flask sqlalchemy object name to alembic.ini Jul 24, 2012
.gitignore Initial commit Jul 18, 2012
LICENSE Initial commit Jul 18, 2012
MANIFEST.in Initial commit Jul 18, 2012
Makefile Initial commit Jul 18, 2012
README.md Update README.md Sep 7, 2012
setup.py Update setup.py Jan 11, 2013



A Flask Extension to provide Alembic integration with Flask.

Development Notes

  • This extension is largely untested at the moment
  • in order to provide a correct usage string it currently needs the trunk of alembic (although it should still work with the pypi version, just that the help displayed will be incorrect)
  • there are quite a lot of dependencies and assumptions at the moment
  • migrate init cannot be called with any arguments - it assumes (for now) a template argument flask and a directory argument alembic

It is intended that these issues will be resolved as development continues! There are probably more bugs than those listed - if you find one please let us know.


Flask-Alembic isn't on pypi yet, so you'll need to install it from the repo:

$ pip install -e git+https://github.com/tobiasandtobias/flask-alembic.git

This should also install the required dependencies. If you want the usage strings for the management command to be correct, you'll need to do:

$ pip uninstall alembic

and then

$ pip install -e hg+https://bitbucket.org/zzzeek/alembic

to get the latest version with the usage string fix.


First, ensure you have a SQLAlchemy object in your flask app:

from flask import Flask
from flask.ext.sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:////tmp/test.db'
db = SQLAlchemy(app)

Please note that one of the assumptions currently made by Flask-Alembic is that your SQLAlchemy object will be called db. If it's not, you can edit the generated alembic alembic.ini file appropriately.

The extension provides a Flask-Script management command wrapper for the alembic command, which you will need to add to e.g. manage.py:

from flask.ext.script import Manager
from flask.ext.alembic import ManageMigrations

manager = Manager(app)
manager.add_command("migrate", ManageMigrations())

if __name__ == "__main__":


You can now use the alembic commands using manage.py migrate, e.g.

$ python manage.py migrate -h

There are some differences, however - you can't currently pass any arguments at all to

$ python manage.py migrate init


$ python manage.py migrate list_templates

since the ManageMigrations command hijacks these in order to provide a custom config object, which then supplies the appropriate flask templates to alembic. See the alembic documentation for more details on the arguments you can use, and how to use alembic.

What Flask-Alembic does

The extension sub-classes alembic.config.Config in order to provide a set of flask-specific templates (see get_template_directory). The provided management command then hijacks init and list_templates in order to pass the flask-specific config.

manage.py migrate init uses the flask templates to create an alembic env.py that sets the alembic sqlalchemy.url config value to the value of SQLALCHEMY_DATABASE_URI in the flask config, thereby avoiding repeating the value in more than one place. It also creates a flask-specific alembic.ini which provides a config value flask_sqlalchemy, which you should change to the name of your Flask app SQLAlchemy object (the default is 'db'). env.py uses this information to import the SQLAlchemy object from the flask app in order to populate target_metadata and enable autogeneration of revisions.