I can't connect to my local database

Diagnoses why a connection to a local PostgreSQL server is failing and routes to the right fix, covering a server that isn't running, wrong credentials or role, a missing database, and a connection limit that has been exhausted.

Run this

Read-only

Attempt a connection with the current environment defaults (PGHOST, PGPORT, PGUSER, PGDATABASE) and capture how it fails

$psql -c "SELECT 1;"

Paste the output

Matched against this step's known patterns to pick the next step.

View full flow

env_mismatchPending
kind: outcome
client_missingPending
kind: outcome
list_databasesPending
kind: recipe_ref
- outcome: success → choose_database
- default → unknown_failure
choose_databasePending
kind: outcome
server_startingPending
kind: outcome
unknown_failurePending
kind: outcome
already_connectsPending
kind: outcome
check_connection (entry)In progress
kind: diagnostic
- match "\(1 row\)" → already_connects
- match "Connection refused|could not connect|No such file or directory" → check_server_ready
- match "password authentication failed|no password supplied|role .* does not exist" → auth_or_role_failure
- match "database .* does not exist" → list_databases
- match "too many clients" → inspect_connections
- match "command not found|not recognized as" → client_missing
- default → unknown_failure
free_connectionsPending
kind: outcome
check_server_readyPending
kind: diagnostic
- match "accepting connections" → env_mismatch
- match "rejecting connections" → server_starting
- default → server_not_running
server_not_runningPending
kind: outcome
inspect_connectionsPending
kind: recipe_ref
- outcome: success → free_connections
- default → unknown_failure
auth_or_role_failurePending
kind: outcome