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_mismatchkind: outcome
client_missingkind: outcome
list_databaseskind: recipe_ref
- outcome: success → choose_database
- default → unknown_failure
choose_databasekind: outcome
server_startingkind: outcome
unknown_failurekind: outcome
already_connectskind: outcome
check_connection (entry)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_connectionskind: outcome
check_server_readykind: diagnostic
- match "accepting connections" → env_mismatch
- match "rejecting connections" → server_starting
- default → server_not_running
server_not_runningkind: outcome
inspect_connectionskind: recipe_ref
- outcome: success → free_connections
- default → unknown_failure
auth_or_role_failurekind: outcome