Airflow "db migrate"/"db upgrade" failed in CI

Airflow runs Alembic migrations against its metadata database with airflow db migrate (formerly db upgrade). It fails when the database is unreachable, the connection string is wrong, or a migration cannot apply to the current schema.

What this error means

A CI setup step running airflow db migrate fails with an OperationalError connecting to the metadata DB, or an Alembic error mid-migration, before any DAG can run.

Airflow

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError)
  connection to server at "localhost" (127.0.0.1), port 5432 failed:
  Connection refused
[SQL: SELECT ... FROM alembic_version]

Common causes

The metadata database is not ready

The migrate step ran before the Postgres/MySQL service container accepted connections, or no database service was started at all.

A wrong or default connection string

AIRFLOW__DATABASE__SQL_ALCHEMY_CONN points at the default SQLite or a wrong host, so the real database is never contacted.

How to fix it

Start the DB and wait for readiness before migrating

Run a Postgres/MySQL service container for the metadata DB.
Set SQL_ALCHEMY_CONN to that service.
Wait until the DB is healthy, then run airflow db migrate.

Terminal

export AIRFLOW__DATABASE__SQL_ALCHEMY_CONN=postgresql+psycopg2://airflow:airflow@localhost:5432/airflow
airflow db migrate

Gate on a service health check

Use a service container with a health check so the migrate step starts only after the DB is up.

.github/workflows/ci.yml

services:
  postgres:
    image: postgres:16
    env: { POSTGRES_PASSWORD: airflow }
    options: >-
      --health-cmd pg_isready --health-interval 10s --health-retries 5

How to prevent it

Wait for the metadata DB health check before migrating.
Set SQL_ALCHEMY_CONN explicitly to the CI database.
Run airflow db migrate once during setup, not per test.