PostgreSQL connection refused: a diagnostic checklist
If PostgreSQL says “connection refused,” check the host, port and listening service first. The connection usually hasn’t reached a database listener that will accept it. Resetting the password won’t fix that part of the connection.
Identify the layer that failed
- Name resolution: check the exact hostname and network DNS.
- Connection refused: check the endpoint, port, listener and active rejection by network controls.
- Timeout: investigate routing, reachability, firewall rules and service health.
- Authentication failed: the server was reached; inspect the username, password and authentication configuration.
- Certificate error: check the SSL mode, hostname and trust chain.
Use the error category to choose what to check next. You’ll still need to verify the cause. PostgreSQL documents connection parameters such as host, port and connection timeout in its connection reference.
Compare the saved connection with the source of truth
Copy the current endpoint from the hosting dashboard or deployment configuration. Confirm that the database is running and that you are using the database port, not an application HTTP port. For a containerized local setup, use the port published to your host when connecting from a desktop app; an internal container name may only resolve inside the container network.
If SSH is involved, check the SSH connection separately from the database destination as seen by the remote host. A successful SSH login does not establish that the database listener is reachable from there.
Check the same endpoint using another client
Use the same database, role, host, port and SSL settings. If both clients fail before authentication, investigate the shared environment. If only one fails, compare the effective settings, including the saved password and root certificate path. Avoid testing against two different endpoints and treating the results as equivalent.
Supabase adds endpoint-specific checks
For a desktop GUI, Supabase recommends the session pooler when IPv4 reachability is needed. Repeated authentication failures can also trigger protective blocks. Follow the provider's connection-refused troubleshooting; do not assume every refusal is an IP-version problem.
Keep database access restricted while investigating. Opening the database to all addresses or turning off certificate verification obscures the cause and changes the security properties of your setup.
Continue reading
Resolve SSL settings · Check Supabase credentials
For the desktop workflow, compare plainDB features on Mac and Windows or download the 14-day trial.