Bun "PostgresError" from bun:sql / postgres in CI

By Kaveh Alemi·Latchkey

A Bun test that talks to Postgres (via bun:sql or the postgres client) failed with a PostgresError. In CI this is almost always a missing or misconfigured database service, not a query bug.

What this error means

bun test fails with "PostgresError" (connection refused, database does not exist, or auth failure) when a test opens a database connection in CI.

(fail) users > inserts a row
PostgresError: connection refused
  at connect (bun:sql)

Common causes

No Postgres service is running in the job

The workflow has no Postgres service container, so the connection is refused when the test dials the database.

A wrong or missing connection string

DATABASE_URL points at the wrong host/port/credentials, or is unset, so the client cannot authenticate or reach the server.

How to fix it

Add a Postgres service and connection URL

1. Declare a Postgres services container in the job.
2. Set DATABASE_URL to that service host and port.
3. Wait for readiness before running tests.

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

Point the client at the service

Set the connection string in the test step env so Bun connects to the CI database.

- run: bun test
  env:
    DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres

How to prevent it

• Provide a Postgres service container for database tests.
• Set DATABASE_URL from the service in the test env.
• Gate tests on a health check so the DB is ready.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation