William Liu

Alembic

Alembic uses SQLAlchemy as the underlying engine to do change management scripts for a relational database. This is similar to Django or Rail’s migration.

Migration Environment

When Alembic starts, it creates the Migration Environment:

myproject  # your application source code
  alembic/  # this directory is the home of the migration environment
    env.py  # this is a python script that is run whenever the alembic migration tool is called (usually connection/configuration)
    README
    script.py.mako  # the Mako template file used to generate new migration scripts; this creates what shows up in 'versions'
    alembic.ini  # the 'generic' configuration file (e.g. for a single generic database configuration)
    versions/  # the directory that holds the individual version scripts; ids in file names use a partial GUID approach
      3512b954651e_add_account.py
      2b1ae634e5cd_add_order_id.py
      3adcc9a56557_rename_username_field.py

Running Migrations or Generating SQL Scripts

In your env.py file, you should determine when to use online mode (run against db) or offline mode (create sql)

Offline Mode

In Alembic, you can generate migrations as SQL scripts instead of running them against the database; this is called offline mode and called with the --sql option. You might use this when access to DDL is restricted and SQL scripts need to be passed to someone with higher privileges.

alembic upgrade ae1027a6acf --sql

Online Mode

In Alembic, you can run your migrations against a database; this is called online mode.

alembic.ini

The file that the alembic script looks for when called. This alembic.ini is a configuration file that points you to where the database migration(s) are, what loggers you have, etc.