Postgres "FATAL: database X does not exist" in CI

Postgres authenticated the connection and then could not find the database named in the connection string. The server is reachable and credentials are valid - the database simply does not exist yet. This is deterministic.

What this error means

psql/migrate fails with "FATAL: database X does not exist". It fails the same way every run because the database name in the URL was never created on the server.

psql

psql: error: connection to server at "localhost", port 5432 failed:
FATAL:  database "app_test" does not exist

Common causes

Database never created

The official Postgres image only creates the database named by POSTGRES_DB. If the URL names a different database, it does not exist.

Name mismatch

A typo or environment mismatch between POSTGRES_DB and the database in DATABASE_URL points the client at a non-existent database.

How to fix it

Create the database via the service env

Have the container create the database your URL expects.

.github/workflows/ci.yml

services:
  postgres:
    image: postgres:16
    env:
      POSTGRES_DB: app_test
      POSTGRES_PASSWORD: postgres
env:
  DATABASE_URL: postgresql://postgres:postgres@localhost:5432/app_test

Or create it explicitly before migrating

Terminal

createdb -h localhost -U postgres app_test || true
psql "$DATABASE_URL" -c 'select 1'

How to prevent it

Keep POSTGRES_DB and the database in DATABASE_URL in sync.
Create the test database as an explicit, idempotent step.
This is deterministic - a retry will not create the database; fix the name or create it.