PgBouncer transactiepooling uitgelegd

PgBouncer biedt drie modi, die alleen verschillen wanneer de Postgres-serververbinding terugkeert naar de gemeenschappelijke pool. De officiële documentatie noemt ze session, transaction en statement (pgbouncer.org/features.html, sectie "Poolingmodi", geraadpleegd op 24 augustus 2026).

De sessiemodus is het meest tolerant, maar het minst effectief wat betreft schaalbaarheid: een Postgres-verbinding blijft gereserveerd voor een client zolang deze verbonden blijft, zelfs als deze tussen twee verzoeken niets doet. De verklaringsmodus is gereserveerd voor zeer specifieke gevallen (alleen-lezen proxy, gezondheidscontroles) en verbreekt zelfs klassieke expliciete transacties. De transactiemodus is het compromis dat in de praktijk domineert voor een REST API: elk HTTP-verzoek komt doorgaans overeen met een enkele korte Postgres-transactie.

In de transactiemodus maakt PgBouncer alleen een serververbinding met een client wanneer deze een transactie opent, en stuurt deze terug naar de pool bij COMMIT of ROLLBACK. Tussen twee transacties kan het voorkomen dat dezelfde client opnieuw wordt toegewezen aan een geheel andere serververbinding.

Concreet kan PgBouncer met een default_pool_size van 20 honderden gelijktijdige klanten absorberen die op een gegeven moment slechts een paar lopende transacties hebben. Het is deze verhouding die de transactiemodus rechtvaardigt voor een REST API met veel verkeer maar korte transacties: de zeldzame bron (een Postgres-verbinding, duur in geheugen aan de serverzijde) wordt alleen bezet voor de tijd die strikt noodzakelijk is.

[pgbouncer]
listen_port = 5432

; La connexion serveur est libérée dès la fin de chaque transaction
pool_mode = transaction

default_pool_size = 80
max_client_conn = 1000

; Ne pas utiliser avec des sessions stateful (SET, advisory locks, LISTEN/NOTIFY)

Deze laatste opmerking vat de essentie samen: de transactiemodus werkt omdat het opzettelijk de link tussen "mijn applicatiesessie" en "mijn Postgres-verbinding" verbreekt. Alles gebaseerd op deze link gaat kapot. In het volgende gedeelte wordt precies vermeld wat.

De officiële PgBouncer-documentatie vermeldt expliciet PostgreSQL-functies die hun betekenis verliezen zodra een serververbinding kan worden gerecycled tussen twee verzoeken van dezelfde client.

De meeste moderne Postgres-stuurprogramma's bereiden standaard benoemde verzoeken aan de protocolkant voor, zonder dat de applicatiecode hier expliciet om vraagt. Dit is precies wat het moeilijk maakt om op deze val te anticiperen.

Een op protocol voorbereide instructie wordt benoemd en in de cache opgeslagen op een specifieke serververbinding, op het moment van Parse. In de transactiemodus kan deze verbinding opnieuw worden toegewezen aan een andere client tussen twee verzoeken van dezelfde logische client. Als het stuurprogramma vervolgens dezelfde instructienaam opnieuw afspeelt op een verbinding waar deze nooit is voorbereid, reageert Postgres met een expliciete fout, meestal prepared statement "sqlx_s_N" does not exist voor een sqlx-client. Het gedrag is intermitterend: het hangt af van hoe de verbindingen presteren onder belasting, en niet van een deterministische bug die bij elke oproep reproduceerbaar is.

De correctie aan de clientzijde is hetzelfde, ongeacht de taal: schakel de cache van benoemde voorbereide instructies uit, of forceer niet-benoemde zoekopdrachten, voor elke pool die een pooler kruist in de transactiemodus. In Rust met sqlx gaat het via statement_cache_capacity(0) over de verbindingsopties.

let connect_options = url
    .parse::<PgConnectOptions>()?
    .statement_cache_capacity(0);

// Equivalenten: asyncpg -> statement_cache_size=0, pgjdbc -> prepareThreshold=0

Sinds versie 1.21 verhelpt PgBouncer een deel van het probleem aan de serverzijde: het kan in het protocol voorbereide instructies volgen in de transactiemodus en deze direct voorbereiden op de toegewezen verbinding, met een LRU-cache per verbinding waarvan de grootte wordt aangepast via max_prepared_statements. Dit vermindert het aantal missers, maar ontslaat u niet van het uitschakelen van de clientcache in een pool met meerdere tenants waar de search_path van het ene verzoek naar het andere verandert: een in de cache opgeslagen plan bevriest de interne identificatie (OID) van de opgeloste tabel op het moment van Parse, en het opnieuw afspelen ervan onder een ander schema kan gegevens van de verkeerde tenant retourneren in plaats van een eenvoudige fout.

De Aurabase-repository implementeert PgBouncer als pool_mode=transaction vóór het gedeelde datavlak (deploy/helm/aurabase/templates/infra/pgbouncer.yaml), en een identiek geconfigureerde Pooler CNPG vóór elke speciale Postgres-instantie van een tenant (deploy/cnpg/tenant-pooler.yaml). Bij beide trajecten wordt dezelfde discipline toegepast als hierboven beschreven.

De broncode documenteert een specifieke veiligheidsreden voor deze keuze, niet alleen een stabiliteitsreden. Postgres-pools die tussen tenants worden gedeeld, positioneren een andere search_path per project op hergebruikte verbindingen. Een in de cache opgeslagen instructie bevriest de OID van de opgeloste tabel op het moment van Parse; Als u de query opnieuw afspeelt voor een andere tenant op dezelfde verbinding, wordt de query uitgevoerd op basis van het schema van de eerste tenant, een isolatie-bypass en niet alleen een toepassingsfout. statement_cache_capacity(0) wordt daarom zonder uitzondering toegepast, ook op speciale instanties die ook in transactiemodus via een CNPG Pooler gaan.

Hygiënemaatregel voor de tweede sessie: wanneer elke verbinding terugkeert naar de pool, voert een hook DISCARD ALL uit (instellingen resetten, de toewijzing van voorbereide instructies aan de serverzijde ongedaan maken, adviesvergrendelingen vrijgeven, cursors en tijdelijke tabellen opschonen). Zonder deze hook zou een sessieresidu van een eerder verzoek kunnen lekken bij het volgende verzoek van een andere tenant die dezelfde gerecyclede verbinding hergebruikt.

Uitzondering geaccepteerd: speciale PostgREST-instanties blijven in directe verbinding met de primaire instantie, zonder via de pooler te gaan. Het herladen van het PostgREST-schema is afhankelijk van LISTEN/NOTIFY, dat uitgaat van een persistente verbinding, precies de functionaliteit die de transactiemodus verbreekt (details zijn al gedocumenteerd in ons artikel over PostgREST-compatibiliteit bij Aurabase). RLS-instellingen per verzoek worden binnen een expliciete transactie doorgegeven aan SET LOCAL, de enige manier om compatibel te blijven met een pool die serververbindingen bij elke COMMIT kan wijzigen (zie ons artikel overmulti-tenant RLS-isolatie).

Een korte checklist, toepasbaar op elke backend die overstapt van een directe Postgres-verbinding naar een PgBouncer in transactiemodus.

1. Controleer de applicatiecode. Zoek naar niet-transactie SET, LISTEN/NOTIFY, sessie-adviesblokkeringen, WITH HOLD cursors en tijdelijke tabellen die tussen query's worden hergebruikt.
2. Vervang sessie-SETs door LOCAL SETs binnen een expliciete transactie. Dit is de enige instelling die het recyclen van verbindingen goed overleeft, omdat deze wordt opgeschoond bij COMMIT/ROLLBACK in plaats van te lekken bij de volgende verbinding.
3. Schakel de cache voor voorbereide instructies aan de bestuurderszijde uit als uw pool de pooler doorloopt en het schema of de rol van het ene verzoek naar het andere verandert. De prestatiekosten zijn reëel maar meetbaar, en veel lager dan het risico op lekkage tussen huurders.
4. Isoleer verbindingen die echt de sessiemodus nodig hebben (migraties, beheerdersscripts, alles wat afhankelijk is van LISTEN/NOTIFY) naar een directe niet-poolerverbinding, in plaats van af te zien van de transactiemodus voor al het andere verkeer.
5. Grootte default_pool_size en max_client_conn relatief ten opzichte van Postgres' werkelijke max_connections, niet door een willekeurig getal gekopieerd uit een ander project.
6. Test onder echte belasting, niet alleen een rooktest. Opgestelde instructiefouten en lekken van sessie-instellingen verschijnen bijna nooit op een enkele lokale verbinding.
7. Monitor SHOW POOLS en SHOW STATS vanaf de PgBouncer-beheerconsole zodra deze in productie is, om poolverzadiging te detecteren voordat deze zichtbaar wordt aan de clientzijde.

Nee, maar het is de juiste standaardkeuze voor de overgrote meerderheid van REST API's. De sessiemodus blijft de voorkeur genieten voor een oudere applicatie die sterk afhankelijk is van sessiefunctionaliteiten die u niet snel kunt herstructureren, of voor weinig verkeer waarbij de poolingwinst de migratie-inspanning niet compenseert.

PgBouncer is ook niet de enige implementatie van dit poolingmodel: Supavisor (Supabase) en PgCat zijn twee recente alternatieven, met verschillende afwegingen op het gebied van belastingverdeling en clustering. Bekijk onze gedetailleerde vergelijking, PgBouncer vs Supavisor vs PgCat, om tussen de drie te kiezen, afhankelijk van uw topologie.

De vragen die het vaakst naar voren komen zodra de transactiemodus in productie is geactiveerd.