psql: error: connection to server refused. Is the server running on host "localhost" and accepting TCP/IP connections on port 5432?

PostgreSQL isn’t running or isn’t accepting connections on the expected port.

Fix 1: Start PostgreSQL

# macOS (Homebrew)
brew services start postgresql

# Linux
sudo systemctl start postgresql
sudo systemctl status postgresql

Fix 2: Check the port

# Default is 5432
sudo lsof -i :5432

Fix 3: Check pg_hba.conf

PostgreSQL might not allow your connection method:

# Find the config
sudo find / -name pg_hba.conf 2>/dev/null

# Add a line for local connections
# local all all trust
# host all all 127.0.0.1/32 md5

Restart after changes: sudo systemctl restart postgresql

Fix 4: Docker — check port mapping

services:
  db:
    image: postgres:16
    ports:
      - "5432:5432"  # host:container