Back to open source

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.

1 app BEGIN; INSERT INTO pp_multi VALUES (1); COMMIT Postgres ok tags 0,1,0 PgDog ok tags 0 2 app disconnect both ok 3 check (direct) SELECT count(*) FROM pp_multi Postgres ok ("1") tags 1 PgDog ok ("0") tags 1
multi-statement-begin through PgDog 0.1.62. Postgres runs all three statements; through PgDog the client gets back only the BEGIN, and a direct check afterwards finds no row.

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.

What a pass used to mean

client a client b SET work_mem SHOW work_mem pooler backend pid 4127 backend pid 4188
Results match, so it passed. But b never reached a's backend: nothing was tested.

What counts now

client a client b SET work_mem SHOW work_mem pooler backend pid 4127
Both clients read pid 4127 through the pooler. Only a run like this counts; if none does, the result is a skip, with the reason.

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:

send = ["parse s1 SELECT 'a'::text", "bind - s1", "execute -", "sync"]

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.

Results on Postgres 18.4
  • 698 pass
  • 132 silent failures
  • 95 errors and hangs
  • 136 documented limitations
PgBouncer
PgDog
PgCat
Odyssey
Supavisor

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

poolproof 0.1.1 results, snapshot of 2026-11-04. Columns are the 50 scenarios, rows the 24 pooler versions and configurations. Select a cell to see what it checks. Full results with every trace

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 BEGIN of BEGIN; INSERT; COMMIT sent 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_path with set_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.

The repository on GitHub