PostgreSQL Server Connection Timeout Monitor

Threat/Impact Level: HIGH | Downtime Risk: HIGH | Time to Fix: 5–30 mins depending on root cause

TL;DR

• What broke: PostgreSQL client cannot establish a TCP connection to the server — the socket handshake never completes before the timeout threshold is hit.
• How to fix it: Isolate the failure layer in order: network/firewall → listen_addresses binding → pg_hba.conf rules → connection pool saturation → server-side max_connections.
• Fast path: Use our Client-Side Sandbox above to auto-refactor this — paste your postgresql.conf, connection string, or pg_hba.conf and get a corrected config without sending secrets to a third-party server.

psql: error: could not connect to server: Connection timed out
        Is the server running on host "db.internal.prod" (10.0.4.22) and accepting
        TCP/IP connections on port 5432?

Error: connect ETIMEDOUT 10.0.4.22:5432
OperationalError: could not connect to server: timeout expired

How to Fix It (The Solution)

Step 1: Confirm the TCP layer first

Before touching any config, confirm whether the port is reachable at all:

# From the application server:
nc -zv 10.0.4.22 5432
traceroute 10.0.4.22

# Check if PostgreSQL is actually listening:
sudo ss -tlnp | grep 5432
# or
sudo netstat -tlnp | grep postgres

If nc times out → the problem is network/firewall, not PostgreSQL config. Check security groups, NACLs, or iptables rules first.

If ss shows PostgreSQL is NOT listening on 0.0.0.0:5432 or your target IP → the problem is listen_addresses.

Basic Fix — `listen_addresses` and `pg_hba.conf`

The most common root cause on a freshly deployed server: PostgreSQL defaults to listening only on localhost.

# /etc/postgresql/15/main/postgresql.conf

- listen_addresses = 'localhost'
+ listen_addresses = '10.0.4.22'   # Bind to the private interface only, NOT '*'

# /etc/postgresql/15/main/pg_hba.conf
# Add an explicit rule for your application subnet

- # No entry for 10.0.5.0/24 (app server subnet)
+ host    myappdb    appuser    10.0.5.0/24    scram-sha-256

After editing:

sudo systemctl reload postgresql
# Reload is sufficient for pg_hba.conf changes.
# postgresql.conf listen_addresses change requires full restart:
sudo systemctl restart postgresql

Enterprise Best Practice — Layered Defense with Connection Pooling and Timeout Tuning

Never expose PostgreSQL directly to application servers in production. Use PgBouncer as a connection proxy and enforce strict timeout budgets at every layer.

# /etc/postgresql/15/main/postgresql.conf

- listen_addresses = '*'
- max_connections = 500
+ listen_addresses = '127.0.0.1'   # PgBouncer runs on the same host or private VLAN
+ max_connections = 100             # PgBouncer manages the pool; DB sees far fewer connections

# Add explicit timeout guards:
- #tcp_keepalives_idle = 0
- #tcp_keepalives_interval = 0
- #tcp_keepalives_count = 0
+ tcp_keepalives_idle = 60
+ tcp_keepalives_interval = 10
+ tcp_keepalives_count = 6
+ statement_timeout = '30s'
+ idle_in_transaction_session_timeout = '60s'

# /etc/pgbouncer/pgbouncer.ini

- listen_addr = *
- auth_type = trust
+ listen_addr = 10.0.4.22          # Private interface only
+ auth_type = scram-sha-256
+ pool_mode = transaction           # Transaction pooling for stateless apps
+ max_client_conn = 1000
+ default_pool_size = 25
+ server_connect_timeout = 10       # Fail fast to PgBouncer; don't let clients block
+ server_idle_timeout = 600
+ client_idle_timeout = 300

# Application-side connection string (example: Python SQLAlchemy)

- DATABASE_URL = "postgresql://appuser:pass@10.0.4.22:5432/myappdb"
+ DATABASE_URL = "postgresql://appuser:pass@10.0.4.22:6432/myappdb"
+                "?connect_timeout=5&application_name=myapp"
# Port 6432 = PgBouncer. connect_timeout=5 ensures fast failure and retry.

💡 Tired of pasting proprietary infrastructure configs into public LLMs? Generic AI interfaces log your company's ARNs, connection strings, and private keys. StackEngine enforces client-side zero-trust boundaries—the sandbox above executes 100% locally in your browser. Drop your broken manifest above to redact secrets locally and synthesize deterministic patch drafts with your own API key.

(For CI/CD pipeline automation, install via npm i -g stackengine).

Firewall / Security Group Rules (AWS/GCP/Azure)

If running on a cloud provider, the silent timeout is almost always a security group or firewall rule:

# AWS Security Group (Terraform)
resource "aws_security_group_rule" "postgres_ingress" {
  type              = "ingress"
  from_port         = 5432
  to_port           = 5432
  protocol          = "tcp"

- cidr_blocks       = ["0.0.0.0/0"]   # NEVER. This is the misconfiguration.
+ source_security_group_id = aws_security_group.app_servers.id  # Restrict to app SG only
}

pip install checkov
checkov -d ./terraform --check CKV_AWS_25   # Checks for unrestricted SG ingress on port 5432

# policy/postgres.rego
package postgres

deny[msg] {
  input.listen_addresses == "*"
  msg := "DENY: listen_addresses must not be set to '*'. Bind to a specific private interface."
}

deny[msg] {
  input.max_connections > 200
  msg := "DENY: max_connections > 200 without a connection pooler is a saturation risk."
}

conftest test postgresql.conf --policy policy/postgres.rego

# .github/workflows/db-smoke-test.yml
- name: PostgreSQL connectivity smoke test
  run: |
    timeout 5 bash -c 'until nc -zv ${{ secrets.DB_HOST }} 5432; do sleep 1; done'
    PGPASSWORD=${{ secrets.DB_PASS }} psql -h ${{ secrets.DB_HOST }} \
      -U appuser -d myappdb -c 'SELECT 1;' --connect-timeout=5

# prometheus/alerts/postgres.yml
- alert: PgBouncerPoolSaturation
  expr: pgbouncer_pools_server_active_connections / pgbouncer_pools_server_pool_size > 0.85
  for: 2m
  labels:
    severity: warning
  annotations:
    summary: "PgBouncer pool is >85% saturated — connection timeouts imminent"