Drizzle "drizzle-kit could not connect to database" in CI

By Daniel Zoghalchali·Latchkey

drizzle-kit reads your connection config and opens a database connection before running. When the database is not yet listening or the URL is wrong, the underlying driver throws ECONNREFUSED and drizzle-kit exits.

What this error means

drizzle-kit migrate or drizzle-kit push fails with a driver connection error such as "ECONNREFUSED 127.0.0.1:5432" before any migration is applied.

Error: connect ECONNREFUSED 127.0.0.1:5432
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:...)

Common causes

The database service is not ready

drizzle-kit runs before the Postgres/MySQL service container is accepting connections, so the connection is refused.

Wrong connection URL in drizzle config

The dbCredentials URL or host/port in drizzle.config.ts does not match where the database actually listens in CI.

How to fix it

Wait for the database before running drizzle-kit

Use a service health check so the migrate step starts only once the database accepts connections.

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

Confirm the config URL matches CI

1. Read dbCredentials in drizzle.config.ts.
2. Set the URL from an env var so CI controls the host and port.
3. Use localhost and the mapped port when the job runs on the runner.

export default defineConfig({
  dialect: 'postgresql',
  dbCredentials: { url: process.env.DATABASE_URL! },
});

How to prevent it

• Gate drizzle-kit behind a database health check.
• Drive the connection URL from an environment variable in CI.
• Keep host/port consistent with how the job is executed.

Frequently asked questions

Related guides

References

• GitHub Actions documentation