# Workflow: connection monitoring runbook

## Goal
Know you are approaching a connection limit before clients feel it.

## Steps
1. Baseline the direct side: `SHOW max_connections;` and the active count:
```sql
SELECT usename, count(*) FROM pg_stat_activity
WHERE datname = '[your-db]' GROUP BY usename;
```
2. Watch the Console Monitoring page's connection graph over a full business cycle; note the peaks.
3. Alert on: direct connections above 70% of max_connections; pooler queueing (slow checkouts); approaching 10,000 client connections.
4. Know which limit each symptom maps to: "too many clients already" = max_connections (direct); "no more connections allowed" = 10,000 pooler clients; queueing with 2-minute timeouts = default_pool_size per user/database.
5. Rehearse the response: shift traffic to pooled, cut per-instance pool sizes, raise compute size.

## Ordering constraints
- Baseline first, alert thresholds second; thresholds from guesses either page constantly or never.

## Traps
- Monitoring only the app side misses direct-connection creep from scripts, BI tools, and forgotten psql sessions.
- Connection counts that grow monotonically across deploys mean a leak; the fix is code, not a bigger compute.

## Verify
A load test that previously caused errors now pages the alert first, and the runbook resolves it without guessing.