hardbyte / hardbyte/awa

Connection-pooler compatibility: NOTIFY self-test, polling fallback, pgbouncer CI leg, docs matrix

Open
#374 0 comments 0 reactions 0 assignees View on GitHub
docs operational
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.