PostgreSQL Localhost 5432 Connection Refused

Threat/Impact Level: HIGH | Downtime Risk: HIGH | Time to Fix: 5–15 mins

TL;DR

• What broke: PostgreSQL is either not running, not listening on 127.0.0.1:5432, or pg_hba.conf is rejecting the connection before it starts.
• How to fix it: Confirm the service is active, verify listen_addresses in postgresql.conf, and check pg_hba.conf allows the connecting user/host.
• Use our Client-Side Sandbox below to paste your postgresql.conf or connection string and auto-generate the corrected config — no data leaves your browser.

could not connect to server: Connection refused
        Is the server running on host "localhost" (127.0.0.1) and accepting
        TCP/IP connections on port 5432?

How to Fix It

Step 1 — Confirm PostgreSQL is Actually Running

# systemd
sudo systemctl status postgresql

# or for versioned installs
sudo systemctl status postgresql@14-main

# If stopped:
sudo systemctl start postgresql

If the service fails to start, check logs immediately:

sudo journalctl -u postgresql --since "10 minutes ago"
# or
tail -100 /var/log/postgresql/postgresql-14-main.log

Step 2 — Confirm It's Listening on TCP Port 5432

sudo ss -tlnp | grep 5432
# Expected output:
# LISTEN  0  128  127.0.0.1:5432  0.0.0.0:*  users:(("postgres",pid=1234,fd=5))

If you see nothing, PostgreSQL is running but bound to a Unix socket only.

Basic Fix — Enable TCP Listening in `postgresql.conf`

# /etc/postgresql/14/main/postgresql.conf

- listen_addresses = ''
+ listen_addresses = 'localhost'

# For remote access (use with firewall rules):
+ listen_addresses = '*'

After editing:

sudo systemctl restart postgresql

Step 3 — Verify `pg_hba.conf` Allows the Connection

# /etc/postgresql/14/main/pg_hba.conf

# Bad: no entry for local TCP connections
- local   all   all                peer

# Good: allow local TCP connections with password auth
+ host    all   all   127.0.0.1/32  scram-sha-256
+ host    all   all   ::1/128        scram-sha-256

Reload after pg_hba.conf changes (no full restart needed):

sudo systemctl reload postgresql
# or inside psql:
SELECT pg_reload_conf();

Enterprise Best Practice — Dockerized / Kubernetes Environments

If running in Docker, the most common cause is the container not being ready when the app starts:

# docker-compose.yml

services:
  app:
    depends_on:
-     - postgres
+     - postgres
+   condition: service_healthy

  postgres:
    image: postgres:15
+   healthcheck:
+     test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER -d $POSTGRES_DB"]
+     interval: 5s
+     timeout: 5s
+     retries: 10

For Kubernetes, ensure the Service targetPort matches the container port and the pod is Running/Ready:

kubectl get pods -l app=postgres
kubectl describe svc postgres-service
kubectl exec -it <app-pod> -- pg_isready -h postgres-service -p 5432

💡 Tired of pasting proprietary infrastructure configs into public LLMs? Generic AI interfaces log your company's ARNs, connection strings, and private keys. StackEngine enforces client-side zero-trust boundaries—the sandbox above executes 100% locally in your browser. Drop your broken manifest above to redact secrets locally and synthesize deterministic patch drafts with your own API key.

(For CI/CD pipeline automation, install via npm i -g stackengine).

# In your deploy script or GitHub Actions step
until pg_isready -h $DB_HOST -p 5432 -U $DB_USER; do
  echo "Waiting for PostgreSQL..."
  sleep 2
done

# If using RDS or Cloud SQL, enforce VPC-only access
resource "aws_db_instance" "postgres" {
  publicly_accessible = false  # Checkov: CKV_AWS_17
}

# .github/workflows/ci.yml
services:
  postgres:
    image: postgres:15
    env:
      POSTGRES_PASSWORD: testpass
    options: >-
      --health-cmd pg_isready
      --health-interval 5s
      --health-timeout 5s
      --health-retries 10

deny[msg] {
  input.kind == "Deployment"
  container := input.spec.template.spec.containers[_]
  not container.readinessProbe
  msg := sprintf("Container '%v' is missing a readinessProbe — DB race condition risk.", [container.name])
}