PostgreSQL connection refused or service unavailable

What this failure means

The application could not connect to PostgreSQL. The service is not responding, not yet started, or the credentials/hostname are wrong.

Symptoms

Faultline looks for one or more of these log fragments:

psql: error: could not connect
pg_isready.*rejecting
could not translate host name

Diagnosis

PostgreSQL connection failures occur when:

• The PostgreSQL service is not running or not yet fully started (common in race conditions).
• The hostname is wrong (e.g., localhost instead of postgres service name in containers).
• The port is wrong or blocked by a firewall.
• Credentials (username, password) are incorrect or not set in environment variables.
• The database does not exist or the user lacks permissions.
• In Kubernetes or Docker Compose, the service has not had time to start.

The error explicitly shows psql: error: could not connect with details about the failed hostname and port.

Fix steps

1. Verify PostgreSQL is running and listening:

   # Local check
   pg_isready -h localhost -p 5432
   
   # Docker container
   docker ps | grep postgres
   
   # Kubernetes
   kubectl get pods -l app=postgres
   

2. Check the connection string and environment variables:

   echo $DATABASE_URL
   env | grep POSTGRES
   env | grep DB
   

3. Verify credentials and hostname:

   psql -h <hostname> -U <username> -d <database> -c "SELECT 1"
   

4. If using Docker Compose or Kubernetes, ensure the service starts before the application:

   Docker Compose example:

   services:
     postgres:
       image: postgres:15
       environment:
         POSTGRES_PASSWORD: secret
     app:
       depends_on:
         - postgres  # Ensures postgres starts first
   

5. Add a health check or retry logic if the service needs startup time:

   for i in {1..30}; do
     pg_isready -h postgres -p 5432 && break
     sleep 1
   done
   

Validation

• pg_isready -h <hostname> -p 5432 returns success.
• psql -h <hostname> -U <username> -d <database> -c "SELECT 1" executes successfully.
• Re-run the application or test suite.

Why it matters

Database connection failures block all data operations. Tests cannot run, migrations cannot execute, and the deployed application cannot serve requests.

Prevention

• Use explicit service dependencies (Docker Compose depends_on, Kubernetes initContainers).
• Add health checks or startup probes to ensure the database is ready.
• Test the connection string in a pre-flight step before running tests.
• Document required environment variables in README.md and .env.example.

Try it locally

pg_isready -h localhost -p 5432
psql -h localhost -U postgres -d postgres -c "SELECT 1"
pg_isready -h localhost -p 5432

How Faultline detects it

Use faultline explain postgres-connection-refused to see the full playbook.

faultline analyze build.log
faultline explain postgres-connection-refused

Generated from playbooks/bundled/log/deploy/postgres-connection-refused.yaml. Do not edit directly.