Alembic "Target database is not up to date" in CI

Alembic found revisions in versions/ newer than the database's current revision. Commands like revision --autogenerate refuse to run against a database that is behind head, to avoid producing a corrupt diff. This is deterministic.

What this error means

alembic revision --autogenerate (or a CI check) aborts with "Target database is not up to date", listing current vs head. It happens when migrations exist but were not applied first.

psql

FAILED: Target database is not up to date.
Current revision(s) for postgresql://...: 9f8e7d6c5b4a
Head(s): a1b2c3d4e5f6

Common causes

Database behind the migration head

New revision files were added but alembic upgrade head was not run, so the current revision lags the latest script.

Autogenerate run before upgrading

Autogenerate requires the database at head first; running it on a behind database is rejected.

How to fix it

Upgrade to head before the guarded command

Terminal

alembic upgrade head
alembic revision --autogenerate -m "add orders status"

Verify current vs head in CI

Run alembic current and alembic heads to see the gap.
Apply the difference with alembic upgrade head.
Always upgrade first so the database is at head before any diff or check.

How to prevent it

Run alembic upgrade head as the first migration step in CI.
Never autogenerate against a database behind head.
This is deterministic - retrying without upgrading fails identically.