Diagnosing Connection Timeouts to DigitalOcean Managed PostgreSQL

Recognizable Condition

A client application repeatedly reports a timeout or connection refused when trying to reach a DigitalOcean Managed PostgreSQL cluster. The connection attempt succeeds on other networks but fails from the current environment.

Typical Causes

Cause	Typical Symptoms
VPC or firewall rule blocks port 5432	Connection attempts silently drop or return "timeout" after the TCP handshake is attempted.
Incorrect connection string	Wrong host, port, or SSL mode; error messages show "could not connect to server" with a timeout.
Cluster in maintenance or degraded state	Cluster shows "maintenance" in the dashboard; connections fail intermittently.
Stale DNS resolution	DNS points to an old IP that no longer hosts the cluster; connection attempts reach the wrong host.

Ordered Diagnostic Checks

1. Verify Firewall Rules
   • Log into the DigitalOcean Control Panel, go to the Managed Database cluster, and open the Firewall tab.
   • Confirm that the client’s public IP or VPC CIDR is listed with access to port 5432.
   • Note: changes take 1–2 minutes to propagate. After editing, wait a minute before re‑testing.
2. Test Network Connectivity from the Client
   • Run a TCP probe:

     nc -vz <cluster-hostname> 5432
     

   • Expected result: Connection to <cluster-hostname> 5432 port [tcp/5432] succeeded! If the line shows “Connection timed out” or “Connection refused”, a network path issue exists.
3. Validate the Connection String
   • Attempt a direct psql connection:

     psql "host=<cluster-hostname> port=5432 user=<user> dbname=<db> sslmode=require"
     

   • Check that sslmode matches the cluster’s requirement (usually require or verify-full). Mismatched SSL settings can cause silent timeouts.
4. Confirm DNS Resolution
   • Resolve the cluster hostname:

     dig +short <cluster-hostname>
     

   • Cross‑reference the returned IP(s) with the IP listed in the DigitalOcean dashboard under the cluster’s Overview section.
   • If the IP differs, the client’s DNS cache may be stale; clear it or use a different resolver.
5. Examine Cluster Health
   • In the DigitalOcean console, view the cluster’s Events or Activity logs.
   • Look for maintenance windows, node failures, or health‑check alerts that could explain intermittent connectivity.

Corrective Actions

• If the firewall is missing the client IP/VPC CIDR, add it under the Firewall tab, select port 5432, and save. Verify connectivity after propagation.
• For incorrect connection strings, update the host, port, user, dbname, and SSL mode to match the cluster’s settings. Test with psql before deploying changes.
• In case of maintenance or degraded state, wait for the cluster to return to healthy status or contact DigitalOcean support if the issue persists beyond the scheduled window.
• If DNS is stale, flush the local resolver cache (systemd-resolve --flush-caches on systemd, sudo dscacheutil -flushcache on macOS) or use a public resolver like 8.8.8.8.

Escalation Criteria

Proceed to support only if:

• All local checks pass but connections still timeout.
• Cluster logs show no maintenance or health issues, yet the client cannot connect.
• You suspect a persistent network or firewall bug beyond your control.

When contacting DigitalOcean, provide:

• Cluster ID and region.
• Exact client IP or VPC CIDR.
• Connection string used.
• Results of nc and psql tests.
• Timestamp of the observed failures.

Practical Verification Checklist

Step	Verification
Firewall rule present	Firewall tab lists client IP/VPC CIDR with port 5432 allowed.
TCP probe succeeds	Output shows “succeeded” for port 5432.
psql connects	Prompt appears without timeout; SELECT 1; returns 1.
DNS matches dashboard	IP from dig equals IP in cluster overview.
Cluster healthy	No maintenance or error events logged.

Limitations

• Firewall changes can take a few minutes to apply; delays may be longer during peak times.
• DigitalOcean’s DNS propagation is usually instant but may lag if the client uses a caching resolver.
• SSL mode mismatches may not produce explicit errors; they can silently cause timeouts.

Example Configuration

Below is a minimal connection string for a managed PostgreSQL cluster named example-db in region nyc3:

psql "host=example-db.nyc3.digitaloceanspaces.com port=5432 user=app_user dbname=app_db sslmode=require"

Replace app_user and app_db with your credentials and database name.