Alembic

Warnings

• breaking target_metadata = None in env.py causes autogenerate to produce completely empty migration files. This is the default after 'alembic init'. Must be changed to Base.metadata.
  Fix: In env.py: import your models then set target_metadata = Base.metadata
• breaking 'Target database is not up to date' error when running --autogenerate. DB must be at head before generating new migrations.
  Fix: Run 'alembic upgrade head' first, then run --autogenerate.
• breaking SQLAlchemy 1.3 support dropped in Alembic 1.15. Python 3.8 support dropped in Alembic 1.15.
  Fix: Use SQLAlchemy >= 1.4 and Python >= 3.9 with Alembic 1.15+
• gotcha Autogenerate cannot detect everything. It misses: stored procedures, views, partial indexes (pre-1.12), CHECK constraints, column defaults (in some cases). Always manually review generated migrations.
  Fix: Always run 'alembic check' and manually review generated migration files before applying.
• gotcha Multiple heads error: 'Multiple head revisions are present' when two migrations both point to the same parent. Happens when multiple developers generate migrations from the same base.
  Fix: Run 'alembic merge heads -m merge' to create a merge migration. Then 'alembic upgrade head'.
• gotcha Autogenerate generates 'create table' for all tables instead of 'add column' when models are not imported before autogenerate runs. Models must be imported in env.py so SQLAlchemy metadata is populated.
  Fix: Import all model files in env.py before target_metadata = Base.metadata.
• gotcha alembic.ini sqlalchemy.url hardcodes the database URL. For production, override it in env.py using environment variables.
  Fix: In env.py: config.set_main_option('sqlalchemy.url', os.environ['DATABASE_URL'])

Install

• pip install alembic Python

Imports

• env.py target_metadata

  # In alembic/env.py — MUST import your models for autogenerate to work
  from myapp.models import Base  # import all models so metadata is populated
  target_metadata = Base.metadata
  
  # If models are in multiple files, import them all:
  from myapp.models.user import User
  from myapp.models.post import Post
  # then:
  target_metadata = Base.metadata

  The single most common Alembic mistake. If target_metadata = None in env.py, autogenerate produces empty migration files. Must import your models and set target_metadata = Base.metadata.
• alembic init + upgrade

  # CLI commands — run from project root
  alembic init alembic          # create alembic directory
  alembic revision --autogenerate -m 'initial'  # generate migration
  alembic upgrade head           # apply all pending migrations
  alembic downgrade -1           # roll back one migration
  alembic history                # show migration history
  alembic current                # show current DB version

  Must run 'alembic upgrade head' before running --autogenerate again. Error: 'Target database is not up to date' means DB is behind the migration chain.

Quickstart

Alembic setup and first migration workflow.

# 1. Install and init
# pip install alembic sqlalchemy
# alembic init alembic

# 2. Edit alembic/env.py — add your models:
# from myapp.models import Base
# target_metadata = Base.metadata

# 3. Edit alembic.ini — set database URL:
# sqlalchemy.url = postgresql://user:pass@localhost/mydb

# 4. Generate first migration
# alembic revision --autogenerate -m 'initial schema'

# 5. Apply migration
# alembic upgrade head

# Migration file (alembic/versions/xxx_initial_schema.py):
from alembic import op
import sqlalchemy as sa

def upgrade():
    op.create_table(
        'users',
        sa.Column('id', sa.Integer, primary_key=True),
        sa.Column('username', sa.String(50), nullable=False),
        sa.Column('email', sa.String(120), nullable=False),
    )

def downgrade():
    op.drop_table('users')