Connection-pooler compatibility: NOTIFY self-test, polling fallback, pgbouncer CI leg, docs matrix
- Dominant language
- Rust
- Stars
- 32
- Forks
- 5
- Avg merge
- 15h 21m
- Merged PRs (30d)
- 21
Description
## Motivation
pgbouncer / pgcat / RDS Proxy are completely undocumented today (zero mentions in `docs/`), and transaction-mode pooling **silently breaks LISTEN/NOTIFY** — Awa's millisecond-pickup mechanism degrades to poll-interval latency with no warning. This is a classic Postgres-queue production trap and a predictable support burden as adoption grows.
## Scope
- **Startup NOTIFY self-test**: on worker start, verify a round-trip; if NOTIFY does not arrive, log an explicit warning naming the likely cause (transaction-mode pooling) and switch to a documented polling fallback cadence.
- **CI leg**: run the integration suite through pgbouncer (session mode and transaction mode) as a nightly matrix dimension.
- **Docs matrix** (`docs/` + operations handbook): per pooler and mode — what works, what degrades, measured pickup-latency deltas (experiment E7 in the roadmap), and recommended configuration (e.g., dedicated direct connection for the LISTEN channel while pooling the rest).
## Acceptance
- Suite green through pgbouncer session mode; transaction-mode behaviour characterized with the fallback engaged and asserted.
- The self-test warning is tested (NOTIFY suppressed → warning + fallback cadence).
- Docs matrix published with measured latency numbers, framed as point-in-time evidence per the 0.6 benchmarking convention.
## References
Roadmap: `docs/0.7-roadmap.md` (WS-3, NEW-10; experiment E7). Related: `awa doctor` NOTIFY check, `docs/deploying-on-managed-postgres.md`.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with docs/0.7-roadmap.md at WS-3, NEW-10, and review the related awa doctor NOTIFY check and docs/deploying-on-managed-postgres.md. Trace the worker startup NOTIFY path and integration suite, then use experiment E7 to define the pgbouncer matrix, warning and fallback assertions, and point-in-time latency documentation. Done means the stated acceptance checks and docs matrix are complete.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- postgresql, rust
- Domain
- backend, ci-cd, databases, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100