The Problem
When you deploy a new version, the old instances must go away. If you kill them immediately, any query or transaction running on those connections is severed mid flight. Users see errors, and uncommitted transactions roll back. Connection draining removes an instance gracefully instead.
How Draining Works
The instance is marked not ready so it receives no new requests, but it keeps serving the ones already in progress:
- Stop accepting new connections at the load balancer or pool.
- Let in flight queries and transactions run to completion.
- Close idle connections and wait up to a drain timeout for the rest.
- Only then shut the instance down.
A bounded timeout matters: a stuck long query should not block the deploy forever, so after the deadline remaining connections are forcibly closed.
Where It Lives
Draining applies to application instances talking to a database and to the database proxy or pooler itself. The pattern is the same: stop new work, finish old work, then exit.
Key idea
Connection draining stops new requests to an instance while letting in flight queries finish within a bounded timeout, avoiding severed transactions and client errors during a deploy.