Data quality checks: warehouse "connection refused" in CI

By Daniel Zoghalchali·Latchkey

A data quality tool tried to open a warehouse connection and got "connection refused". The database service is not running in CI, or the host and port point somewhere nothing is listening.

What this error means

Great Expectations, Soda, dbt, or a pytest query fails at connect time with "connection refused" or "could not connect to server", before any check runs.

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError)
connection to server at "localhost" (127.0.0.1), port 5432 failed:
Connection refused

Common causes

No warehouse service in the job

The pipeline expects a live database but none was started as a service container, so nothing listens on the port.

The tool connected before the service was ready

The database container is still starting; the quality step runs before it accepts connections.

How to fix it

Run the warehouse as a service with a health check

1. Add the database as a service container.
2. Add a health check so the job waits until it accepts connections.
3. Point the tool at the service host and port.

services:
  postgres:
    image: postgres:16
    env: { POSTGRES_PASSWORD: postgres }
    ports: ['5432:5432']
    options: >-
      --health-cmd "pg_isready -U postgres" --health-interval 5s
      --health-timeout 5s --health-retries 10

Wait for readiness before checks

Even with a service, wait on the port explicitly before running validations so a slow start does not fail the step.

until pg_isready -h localhost -p 5432; do sleep 1; done

How to prevent it

• Define the warehouse as a service container with health checks.
• Wait on readiness before quality steps.
• Use the service hostname, not localhost, where the network requires it.

Frequently asked questions

Related guides

References

• GitHub Actions documentation