Connection failures

Connection failures When queries never reach the database. Everything here raises ConnectionError or TimeoutError, not a constraint error — if you are seeing the latter, the database is fine and the problem is the data. What prorm retries, and what it does not isRetryableError() is the whole policy, and it is deliberately narrow: A refused connection, a failed handshake and a rejected password are not retried — retrying them would fail identically, and hammering a database that is refusing you is how a brief outage becomes a long one. Tuning the policy Turn backoff on. Fixed-interval retries from every instance at once produce a thundering herd against a database that is already struggling; exponential backoff spreads them out. match takes message patterns for driver errors prorm does not classify itself — Db2's SQL30081N, for instance. The failures, and what each means Symptom | Usually | --- | --- | ECONNREFUSED | Nothing listening: wrong port, or the database is down. Not retried. | ETIMEDOUT / CONNECTIONTIMEDOUT | A network path problem — security group, firewall, or a saturated host. Retried. | HOSTNOTREACHABLE | DNS or routing. Retried, but if DNS is wrong it will keep failing. | Authentication failed | Credentials changed under you. See Credential rotation. | too many connections | The server's limit, not the pool's. Lower pool.max × instance count below it. | Timeouts while the database is idle | The pool is exhausted, not the engine. | Pool exhaustion looks like a slow database The clearest tell: query latency climbs while database CPU stays flat. Requests are waiting for a connection, not for an answer. Two causes, in order of likelihood: 1. A leak. A transaction that threw before commit or rollback holds its connection until acquire gives up. Always release in a finally, or use the callback form of transaction(), which does it for you. 2. Genuinely too small. pool.max multiplied by the number of application instances must stay under the server's connection limit — and leave room for migrations and your own psql session. Checking connectivity from the process that is failing Run it from the machine that is failing, not your laptop. Most "the database is down" incidents are one instance's networking, not the database. Related reading Connection pooling — sizing in detail Error handling — the error classes Failover — when the connection drops because the host moved