Alembic Autogenerate Produces Empty or Wrong Migration in CI

Alembic autogenerate compares your model metadata against the database. If env.py never imports the models (so target_metadata is empty) it generates a no-op; if the DB is behind head it refuses to autogenerate at all.

What this error means

A CI check that runs alembic revision --autogenerate either emits an empty upgrade()/downgrade() (missing your new column/table) or fails with Target database is not up to date. The model change is real but Alembic does not see it.

Alembic output

FAILED: Target database is not up to date.
# or an empty migration:
def upgrade():
    pass

Common causes

Models not imported into target_metadata

Autogenerate diffs target_metadata against the DB. If env.py does not import the modules that register your tables, the metadata is empty and nothing is detected.

Database not at head

Alembic refuses to autogenerate when the DB is behind the latest revision. alembic upgrade head must run first so the comparison baseline is current.

How to fix it

Import models so metadata is populated

Ensure env.py imports the package that defines all models before setting target_metadata.

env.py

# alembic/env.py
from myapp.models import Base  # imports all model modules
target_metadata = Base.metadata

Upgrade to head, then autogenerate

Terminal

alembic upgrade head
alembic revision --autogenerate -m "add column"

Verify in CI that no diff is pending

Run alembic upgrade head against a fresh DB.
Run alembic check (or autogenerate to a temp file) to assert models match migrations.
Fail the job if a non-empty migration would be generated.

How to prevent it

Import all model modules in env.py so target_metadata is complete.
Run alembic upgrade head before autogenerating in CI.
Add an alembic check step to catch model/migration drift.