alembic upgrade head: Apply Migrations in CI
alembic upgrade head runs every migration revision from the current database version up to the newest head.
Alembic is SQLAlchemy migrations. upgrade head is the deploy command; it walks the revision chain and records the current revision in the alembic_version table.
What it does
alembic upgrade head applies each pending revision in dependency order until the database reaches the latest head. You can also upgrade to a specific revision or a relative one like +1. The current revision is stored in alembic_version.
Common usage
# reads sqlalchemy.url from alembic.ini or env
alembic upgrade head
# override the URL for CI
alembic -x dbUrl="$DATABASE_URL" upgrade head
# or set it in env and read it in env.py
DATABASE_URL="$DATABASE_URL" alembic upgrade headOptions
| Arg / flag | What it does |
|---|---|
| upgrade head | Upgrade to the latest revision |
| upgrade <rev> | Upgrade to a specific revision id |
| upgrade +1 | Apply the next single revision |
| -c <alembic.ini> | Config file path |
| -x <key=value> | Pass a value into env.py (e.g. a URL) |
In CI
Run alembic upgrade head before the app starts. Alembic does not lock by default, so serialize migration jobs or use a database advisory lock in env.py if multiple runners could race. Point sqlalchemy.url at the CI database via env rather than committing credentials into alembic.ini.
Common errors in CI
"Target database is not up to date" appears from commands like revision --autogenerate when the database is behind the code; run alembic upgrade head first. "Can't locate revision identified by 'abc123'" means the alembic_version points at a revision not present in the code (a squashed or missing migration file); restore it or stamp a known revision. "Multiple head revisions are present" means branching that needs a merge revision.