What a connection pooler changes
Poolers are meant to be invisible to the application. poolproof checks that claim: it runs the same small scenarios against Postgres and through a pooler, and reports every step where the answers differ. Most of the work went into making sure a pass actually means something.
Nihal-Pandey-2302/poolproof v0.1.1, 4 Nov 2026 Rust MIT OR Apache-2.0 results site
The problem
PgBouncer, PgDog, Supavisor, PgCat and Odyssey sit between an application and Postgres and share a few server
connections among many clients. In transaction mode a client holds a server connection only for the length of a
transaction, so anything that lives on the connection instead of in the transaction is at risk: a
SET, a temp table, a prepared statement, an advisory lock.
Most poolers document some of this. There was no way to check across poolers and versions which of these actually break and how.
Postgres as the oracle
A poolproof scenario is a short script of steps from one or more clients. It runs twice: once against Postgres directly, once through the pooler, and every step's result is compared. Postgres is the reference, so no scenario hardcodes the answer it expects.
A difference is not just a failure. What matters is how the application finds out:
- Silent: the pooler answers, and the answer is wrong.
- Error: the pooler refuses, so at least the application knows.
- Hang: no reply at all, until something times out.
- Documented: a failure the pooler's own docs describe. Still a failure, but not a bug.
A pass that meant nothing
The first version compared the two runs step by step and called it a pass when they matched. That turned out to
be weaker than it looked. To test whether a SET leaks from one client to another, the two clients
have to land on the same server connection. In transaction mode they may simply never do so, and then "no leak"
only means "never shared".
So steps can now be marked as evidence. Through the pooler they read the backend's process id; on Postgres directly, its start time. A run counts only if the clients really did share a backend. If no run does, the result is not a pass but a skip, with the reason spelled out: the second client never reached the first one's server connection.
Checking the pool before trusting it
Before any scenario runs, poolproof probes the pool's real shape: when a second client arrives while the first is busy, does it wait, get its own backend, or get refused? Scenarios that need exactly one server connection skip when the pool turns out to have several, so a result is never trusted on a pool that isn't the shape its configuration claims.
A failure blamed on the wrong pooler
With several poolers in one test bed, one pooler's leaked advisory lock (a backend that kept it after its client left) made a scenario on a different pooler hang, and the failure looked like that pooler's bug.
The fix is a reset before each scenario that ends only the target pooler's backends, matched by process id, start time, user and address, and then waits for the pooler to answer again. Later a CI run still found a disconnected client's lock held, because a backend exits asynchronously; the check now waits for those backends to be gone before reading their state.
Results that flip
Some results are timing-sensitive and change between runs. Retrying until they pass would hide exactly the behaviour worth reporting. Instead a scenario can run several times, fails if any run fails, and reports how many did. A known-flaky list covers the rest, each entry as narrow as possible and citing the CI run that showed it.
Documented is a claim that needs a source
A failure is marked documented only when an entry quotes the pooler's own documentation word for word, at a pinned commit. A test checks every entry against the committed results, so a stale entry fails CI. And a bug that has been reported upstream is never marked documented, even when the docs half cover it.
Speaking the protocol directly
Some bugs live below SQL. The Rust client poolproof started on gives every prepared statement a globally unique name, which made it impossible to test two clients using the same statement name. So scenarios can also send raw wire-protocol messages through a small client of its own, with SCRAM and MD5 authentication:
That is how it tests Flush, pipelining, COPY and statement-name collisions.
The results
The grid below is Postgres 18.4: 50 scenarios across 24 pooler versions and configurations, 13 core targets plus 11 variants (session mode, a pool of four, non-default settings) that run nightly. 698 pass, 132 fail silently, 95 error or hang, and 136 are documented limitations. The core targets also run on Postgres 17.11. Select a cell to see what it checks and where the answers split.
- 698 pass
- 132 silent failures
- 95 errors and hangs
- 136 documented limitations
multi-statement-begin
A simple query that starts with BEGIN must run every statement in the string.
PgDog 0.1.62silent failure
step 1app simple: BEGIN; INSERT INTO pp_multi VALUES (1); COMMIT
Postgresok tags 0,1,0
PgDogok tags 0
What it found
The scenarios are built from 14 upstream issues. Some reproduce on the versions tested; others show a fix holding. Four of the clearest:
-
PgDog 0.1.50 to 0.1.62 answers only the
BEGINofBEGIN; INSERT; COMMITsent as one string, and never commits the insert if the client disconnects (pgdog#1849, reported by ewhauser). - Supavisor 2.9.13 hangs on four pipelined requests in 9 of 10 runs (supavisor#1239, reported by richardwattie). The 2.10.0 release candidate answers them.
-
PgBouncer 1.26.1 on Postgres 18 drops a client that set an empty
search_pathwithset_config(), once another client has changed it (pgbouncer#1663, reported by AKutlakhmetov). - Every pooler but Odyssey, with default settings, keeps a session advisory lock after the client that took it disconnects (pgdog#1407, reported by mhenrixon). PgBouncer, PgDog, PgCat and Supavisor document this one.
From a red cell to a fix
The PgDog bug shows why silent failures matter. On the issue, a team reported running a migration through PgDog
as one multi-statement transaction and disconnecting. The client saw success. Neither the
ALTER TABLE nor the UPDATE ran.
The cause is in how PgDog routes a multi-statement query on a single shard: by its first statement only. When
that statement is BEGIN, COMMIT or ROLLBACK, PgDog answers it itself, and
the rest of the string is either replayed later with its results thrown away, or dropped.
PgDog currently takes outside fixes as linked branches rather than pull requests, so I posted the cause on the issue with a branch: in that case the whole string goes to the server unchanged, which is what already happens with PgDog's query parser off. It has a unit test and an integration test that fails on main (fix/multi-stmt-begin). It is not merged.
Running poolproof against the branch and its parent, multi-statement-begin goes from fail to pass on Postgres 17
and 18, and nothing else regresses. The related shapes pass on the branch too: COMMIT first, a
BEGIN left open, other spellings of BEGIN, and the extended-protocol shape.
What is still open
Two shapes still fail on the branch, for a separate reason. And the branch's own test expects
SELECT 1 to succeed after the aborted string, where Postgres returns 25P02: the test
encodes the pooler's behaviour, not Postgres's. Exactly the kind of difference poolproof exists to catch.
RDS Proxy and hosted poolers are not in the test bed yet; the docs have recipes for testing them by hand.