Postgres "SSL connection is required" / sslmode in CI

By Kaveh Alemi·Latchkey

The Postgres server is configured to require TLS, and the client connected without it. The server rejects the non-SSL connection (often as a pg_hba.conf entry mismatch with "SSL off"). This is a configuration mismatch, not a transient fault.

What this error means

Connecting to a managed/remote Postgres from CI fails with "no pg_hba.conf entry for host ... SSL off" or "SSL connection is required". It is deterministic until the client enables TLS.

psql

psql: error: connection to server at "db.example.com", port 5432 failed:
FATAL:  no pg_hba.conf entry for host "203.0.113.10", user "app",
database "app", no encryption

Diagnose it: connectivity, then migration state

Migration failures in CI are usually the database not being ready rather than the migration being wrong. A service container accepts TCP connections before it is ready to serve queries, so a migration started too early fails in confusing ways.

Terminal

# wait for readiness, not just for the port to open
until pg_isready -h localhost -p 5432; do sleep 1; done

# then inspect what the tool believes has been applied
<migrate-tool> status

Common causes

Server enforces TLS, client did not request it

Managed Postgres (RDS, Cloud SQL, Neon, Supabase) commonly requires SSL. A connection string without sslmode defaults to a non-SSL attempt that the server refuses.

sslmode set too low

sslmode=disable or prefer against a TLS-required server yields a rejected or downgraded connection.

How to fix it

Require SSL in the connection string

Add sslmode=require (or stricter) so the client negotiates TLS.

.github/workflows/ci.yml

env:
  DATABASE_URL: postgresql://app:${{ secrets.DB_PASSWORD }}@db.example.com:5432/app?sslmode=require

Provide a CA for verify-full

For verified TLS, set sslmode=verify-full and sslrootcert to the provider CA bundle.
Store the CA file in the repo or fetch it in a setup step.
Confirm the host in the URL matches the certificate subject.

How to prevent it

Default to sslmode=require for any remote/managed database in CI.
Keep the CA bundle available for verify modes.
This is deterministic - retrying without TLS will not succeed; enable SSL.

Frequently asked questions

What causes Postgres "SSL connection is required" / sslmode in CI?

There are 2 common causes: server enforces tls, client did not request it and sslmode set too low. Managed Postgres (RDS, Cloud SQL, Neon, Supabase) commonly requires SSL.

How do I fix Postgres "SSL connection is required" / sslmode in CI?

There are 2 fixes depending on which cause you have: require ssl in the connection string and provide a ca for verify-full. Work through them in order, since the first is the most common.

What does Postgres "SSL connection is required" / sslmode in CI actually mean?

Connecting to a managed/remote Postgres from CI fails with "no pg_hba.conf entry for host ...

How do I stop Postgres "SSL connection is required" / sslmode in CI happening again?

Default to sslmode=require for any remote/managed database in CI. The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation