Pooling connessioni PostgreSQL: pooling in-app vs PgBouncer

Perché i picchi di latenza spesso iniziano con le connessioni

Una connessione al database è come una linea telefonica tra la tua app e Postgres. Aprirne una costa tempo e risorse su entrambi i lati: setup TCP/TLS, autenticazione, memoria e un processo backend sul lato Postgres. Un connection pool mantiene aperto un piccolo insieme di queste “linee telefoniche” così la tua app può riutilizzarle invece di ristabilire la connessione per ogni richiesta.

Quando il pooling è disattivato o dimensionato male, raramente vedi un errore netto per primo. Vedi lentezza casuale. Richieste che normalmente impiegano 20–50 ms all'improvviso ne impiegano 500 ms o 5 secondi, e il p95 schizza. Poi compaiono timeout, seguiti da “too many connections”, o una coda dentro l'app mentre aspetta una connessione libera.

I limiti di connessione contano anche per app piccole perché il traffico è a raffiche. Una mail di marketing, un cron job o qualche endpoint lento possono far sì che decine di richieste colpiscano il DB nello stesso istante. Se ogni richiesta apre una nuova connessione, Postgres può spendere molta capacità solo ad accettare e gestire connessioni invece di eseguire query. Se hai già un pool ma è troppo grande, puoi sovraccaricare Postgres con troppi backend attivi e generare context switching e pressione sulla memoria.

Fai attenzione ai sintomi precoci come:

• picchi di latenza p95/p99 mentre la latenza media sembra ok
• timeout che si raggruppano durante i burst di traffico
• aumento del “waiting for connection” nell'app
• frequenti connect/disconnect o saturazione delle connessioni su Postgres

Il pooling riduce il churn delle connessioni e aiuta Postgres a gestire i burst. Non risolverà SQL lenti. Se una query sta facendo una scansione completa della tabella o aspetta lock, il pooling cambia per lo più il modo in cui il sistema fallisce (queueing prima, timeout dopo), non se è veloce.

App pooling vs PgBouncer: quale problema risolvono

Il connection pooling serve a controllare quante connessioni al database esistono contemporaneamente e come vengono riutilizzate. Puoi farlo dentro l'app (app-level pooling) o con un servizio separato davanti a Postgres (PgBouncer). Risolvono problemi correlati ma diversi.

Il pooling a livello di app (in Go, di solito il pool built-in di database/sql) gestisce le connessioni per processo. Decide quando aprire una nuova connessione, quando riutilizzarne una e quando chiudere quelle inattive. Questo evita di pagare il costo di setup per ogni richiesta. Quello che non può fare è coordinarsi fra più istanze dell'app. Se esegui 10 repliche, hai effettivamente 10 pool separati.

PgBouncer si mette fra la tua app e Postgres e fa pooling per conto di molti client. È più utile quando hai molte richieste di breve durata, molte istanze dell'app o traffico a raffiche. Limita le connessioni server verso Postgres anche se arrivano centinaia di client contemporaneamente.

Una divisione semplice delle responsabilità:

• Il pooling in-app modella la concorrenza dentro un'istanza dell'app ed evita reconnect per richiesta.
• PgBouncer limita le connessioni totali a Postgres attraverso tutte le istanze e smussa i burst.
• Postgres ha comunque limiti su CPU, IO e memoria. Il pooling non crea capacità.

Possono lavorare insieme senza problemi di “double pooling” purché ogni livello abbia uno scopo chiaro: un sensato database/sql pool per processo Go, più PgBouncer per far rispettare un budget globale di connessioni.

Una confusione comune è pensare “più pool significa più capacità.” Di solito vuol dire il contrario. Se ogni servizio, worker e replica ha un pool grande, il conteggio totale delle connessioni può esplodere e causare queueing, context switching e picchi improvvisi di latenza.

Come si comporta davvero il pooling in database/sql di Go

In Go, sql.DB è un gestore di pool di connessioni, non una singola connessione. Quando chiami db.Query o db.Exec, database/sql cerca di riutilizzare una connessione idle. Se non ci riesce, può aprirne una nuova (fino al tuo limite) o mettere la richiesta in attesa.

Quell'attesa è spesso l'origine della “latenza misteriosa”. Quando il pool è saturato, le richieste fanno coda dentro l'app. Dall'esterno sembra che Postgres sia lento, ma il tempo è in realtà speso aspettando una connessione libera.

Le manopole che contano

La maggior parte della messa a punto si riduce a quattro impostazioni:

• MaxOpenConns: limite rigido sulle connessioni aperte (idle + in uso). Quando lo raggiungi, le chiamate bloccano.
• MaxIdleConns: quante connessioni possono restare pronte per il riuso. Troppo basso causa reconnect frequenti.
• ConnMaxLifetime: forza il riciclo periodico delle connessioni. Utile per load balancer e timeout NAT, ma troppo basso crea churn.
• ConnMaxIdleTime: chiude connessioni inutilizzate da troppo tempo.

Il riuso delle connessioni di solito abbassa la latenza e la CPU del DB perché eviti setup ripetuti (TCP/TLS, auth, inizializzazione della sessione). Ma un pool sovradimensionato può fare il contrario: permette più query concorrenti di quante Postgres possa gestire bene, aumentando contesa e overhead.

Pensa ai totali, non per processo. Se ogni istanza Go permette 50 connessioni aperte e scala a 20 istanze, hai effettivamente permesso 1.000 connessioni. Confronta quel numero con quanto il tuo server Postgres può effettivamente gestire.

Un punto di partenza pratico è legare MaxOpenConns alla concorrenza attesa per istanza, poi validare con metriche di pool (in-use, idle e wait time) prima di aumentarlo.

Nozioni base su PgBouncer e modalità di pooling

PgBouncer è un piccolo proxy tra la tua app e PostgreSQL. Il servizio si connette a PgBouncer, e PgBouncer mantiene un numero limitato di connessioni reali verso Postgres. Durante i picchi, PgBouncer mette in coda il lavoro dei client invece di creare immediatamente più backend Postgres. Quella coda può fare la differenza tra un rallentamento controllato e un database che va in tilt.

Le tre modalità di pooling

PgBouncer ha tre modalità di pooling:

• Session pooling: un client mantiene la stessa connessione server per tutta la durata della connessione.
• Transaction pooling: un client prende in prestito una connessione server per la durata di una transazione, poi la restituisce.
• Statement pooling: un client prende in prestito una connessione server per una singola istruzione.

Il session pooling si comporta più come connessioni dirette a Postgres. È il meno sorprendente, ma risparmia meno connessioni server durante carichi bursty.

Cosa di solito si adatta alle API HTTP in Go

Per le API HTTP tipiche in Go, la transaction pooling è spesso un buon default. La maggior parte delle richieste esegue una piccola query o una breve transazione, poi termina. La transaction pooling permette a molte connessioni client di condividere un budget di connessioni Postgres più piccolo.

Il compromesso è lo stato di sessione. In transaction mode, tutto ciò che presuppone che una singola connessione server rimanga assegnata può rompersi o comportarsi in modo strano, inclusi:

• prepared statement creati una volta e riutilizzati dopo
• impostazioni di sessione che ti aspetti persistano (SET, SET ROLE, search_path)
• tabelle temporanee e advisory lock usati across statements

Se la tua app dipende da questo tipo di stato, il session pooling è più sicuro. Lo statement pooling è il più restrittivo e raramente adatto alle web app.

Una regola utile: se ogni richiesta può impostare ciò che serve dentro una singola transazione, la transaction pooling tende a mantenere la latenza più stabile sotto carico. Se hai bisogno di comportamento di sessione a lungo termine, usa session pooling e concentra i limiti più rigidi nell'app.

Come scegliere la strategia giusta per un backend Go

Se gestisci un servizio Go con database/sql, hai già il pooling lato app. Per molte squadre questo è sufficiente: poche istanze, traffico stabile e query non estremamente spike. In quel contesto, la scelta più semplice e sicura è ottimizzare il pool Go, mantenere realistico il limite delle connessioni al database e fermarti lì.

PgBouncer aiuta soprattutto quando il database viene colpito da troppe connessioni client contemporanee. Questo si manifesta con molte istanze dell'app (o scaling in stile serverless), traffico a raffiche e molte query brevi.

PgBouncer può anche essere dannoso se usato nella modalità sbagliata. Se il tuo codice dipende da stato di sessione (tabelle temporanee, prepared statement riusati tra richieste, advisory lock tenuti tra chiamate o impostazioni di sessione), la transaction pooling può causare fallimenti confusi. Se hai veramente bisogno del comportamento di sessione, usa session pooling o evita PgBouncer e dimensiona con cura i pool delle app.

Una regola decisionale semplice

Usa questa regola empirica:

• Se hai 1–3 istanze dell'app e le connessioni aperte totali restano comodamente sotto il limite del DB, usa solo il pooling in-app.
• Se hai molte istanze o autoscaling, e la somma dei max open connections potrebbe superare ciò che Postgres può gestire, aggiungi PgBouncer.
• Se la maggior parte delle richieste è breve (letture rapide, scritture piccole), PgBouncer di solito conviene.
• Se le richieste tengono la connessione a lungo (report lenti, transazioni lunghe), prima sistema le query e sii conservativo con le dimensioni dei pool.

Passo dopo passo: dimensionare e distribuire il pooling in sicurezza

I limiti di connessione sono un budget. Se lo spendi tutto in una volta, ogni nuova richiesta aspetta e la tail latency salta. L'obiettivo è limitare la concorrenza in modo controllato mantenendo il throughput.

Una sequenza pratica di rollout

1. Misura i picchi odierni e la latenza ai tail. Registra le connessioni attive di picco (non le medie), più p50/p95/p99 per le richieste e le query chiave. Nota eventuali errori di connessione o timeout.

2. Imposta un budget sicuro di connessioni Postgres per l'app. Parti da max_connections e sottrai spazio per accesso admin, migrazioni, job in background e spike. Se più servizi condividono il DB, dividi il budget intenzionalmente.

3. Mappa il budget ai limiti Go per istanza. Dividi il budget dell'app per il numero di istanze e imposta MaxOpenConns su quel valore (o leggermente più basso). Imposta MaxIdleConns abbastanza alto da evitare reconnect costanti e imposta lifetimes così le connessioni si riciclano occasionalmente senza churn.

4. Aggiungi PgBouncer solo se serve e scegli una modalità. Usa session pooling se ti serve stato di sessione. Usa transaction pooling quando vuoi la maggiore riduzione delle connessioni server e la tua app è compatibile.

5. Distribuisci gradualmente e confronta prima e dopo. Cambia una cosa alla volta, fai canary, poi confronta latenza ai tail, tempo di attesa del pool e CPU del DB.

Esempio: se Postgres può concedere in sicurezza 200 connessioni al tuo servizio e hai 10 istanze Go, parti con MaxOpenConns=15-18 per istanza. Questo lascia spazio per i burst e riduce la probabilità che ogni istanza colpisca il tetto simultaneamente.

Metriche da osservare per intercettare i problemi presto

I problemi di pooling raramente si mostrano prima come “too many connections.” Più spesso vedi una lenta crescita del tempo di attesa e poi un salto improvviso di p95 e p99.

Parti da ciò che l'app Go riporta. Con database/sql monitora open connections, in-use, idle, wait count e wait time. Se il wait count cresce mentre il traffico è stabile, il pool è sottodimensionato o le connessioni vengono trattenute troppo a lungo.

Dal lato database, traccia connessioni attive vs max, CPU e attività di lock. Se la CPU è bassa ma la latenza è alta, spesso è queueing o lock, non capacità di calcolo.

Se usi PgBouncer, aggiungi una terza visuale: client connections, server connections verso Postgres e profondità della coda. Una coda crescente con server connections stabili è un segno chiaro che il budget è saturo.

Buoni segnali di alert:

• p95/p99 in aumento mentre p50 resta normale
• aumento del connection wait time (lato app), specialmente prima dei timeout
• coda di PgBouncer che cresce più di quanto defluisce
• tasso di errori e timeout che aumentano insieme
• crescita dei lock parallela a query di lunga durata

Misconfigurazioni comuni che causano picchi

I problemi di pooling spesso si manifestano durante i burst: le richieste si accumulano in attesa di una connessione, poi tutto torna normale. La causa radice è spesso un'impostazione ragionevole su una singola istanza ma pericolosa quando si eseguono molte copie del servizio.

Cause comuni:

• MaxOpenConns impostato per istanza senza un budget globale. 100 connessioni per istanza su 20 istanze sono 2.000 connessioni potenziali.
• Troppe connessioni idle. I backend idle consumano comunque memoria e possono soffocare altro lavoro.
• ConnMaxLifetime / ConnMaxIdleTime impostati troppo bassi. Questo può scatenare reconnect storms quando molte connessioni si riciclano contemporaneamente.
• PgBouncer in transaction pooling con codice che dipende dallo stato di sessione. Temp table, advisory lock e impostazioni di sessione possono rompersi in modi sottili.
• Job in background e health check che generano burst. Ping a intervallo corto o pattern “apri e chiudi per richiesta” possono creare onde di nuove connessioni.

Un modo semplice per ridurre i picchi è trattare il pooling come un limite condiviso, non un default locale all'app: limita le connessioni totali tra tutte le istanze, mantieni un pool idle modesto e usa lifetimes abbastanza lunghi da evitare reconnect sincronizzati.

Cosa fare quando la domanda supera il budget di connessioni

Quando il traffico esplode, di solito vedi uno di tre esiti: le richieste fanno coda aspettando una connessione libera, le richieste fanno timeout, oppure tutto rallenta così tanto che i retry si accumulano.

Il queueing è il più subdolo. Il tuo handler è ancora in esecuzione, ma è parcheggiato in attesa di una connessione. Quell'attesa diventa parte del tempo di risposta, quindi un pool piccolo può trasformare una query da 50 ms in un endpoint di più secondi sotto carico.

Un modello mentale utile: se il tuo pool ha 30 connessioni utilizzabili e improvvisamente hai 300 richieste concorrenti che necessitano del DB, 270 di esse devono aspettare. Se ogni richiesta tiene la connessione per 100 ms, la latenza ai tail sale rapidamente a secondi.

Imposta un chiaro budget di timeout e rispettalo. Il timeout dell'app dovrebbe essere leggermente più corto del timeout del database così fallisci velocemente e riduci la pressione invece di lasciare il lavoro appeso.

• App: una deadline per la richiesta, più una deadline più corta attorno alla chiamata al DB
• DB: statement_timeout così una query cattiva non può occupare le connessioni per sempre
• Pooler (se usato): un pool wait timeout, così ricevi un rifiuto invece di una coda infinita

Poi aggiungi backpressure per non sovraccaricare il pool in primo luogo. Scegli uno o due meccanismi prevedibili, come limitare la concorrenza per endpoint, scartare traffico con errori chiari (es. 429) o separare job in background dal traffico utente.

Infine, risolvi prima le query lente. Sotto pressione di pooling, le query lente tengono le connessioni più a lungo, il che aumenta le attese, i timeout e i retry. Quello è il loop che trasforma “un po' lente” in “tutto è lento”.

Load testing e capacity planning senza lavoro di intuito

Tratta i load test come un modo per validare il tuo budget di connessioni, non solo throughput. L'obiettivo è confermare che il pooling si comporta sotto pressione come in staging.

Testa con traffico realistico: stesso mix di richieste, pattern di burst e lo stesso numero di istanze dell'app che usi in produzione. I benchmark su “un solo endpoint” spesso nascondono i problemi di pool fino al giorno del lancio.

Includi un warm-up così non misuri cache fredde ed effetti di ramp-up. Lascia che i pool raggiungano la loro dimensione normale, poi inizia a registrare i numeri.

Se confronti strategie, mantieni il carico identico e esegui:

• solo app pooling (tuned database/sql, senza PgBouncer)
• PgBouncer davanti (le app tengono pool piccoli, PgBouncer cap le connessioni server)
• entrambi insieme (pool app piccoli + PgBouncer)

Dopo ogni run, registra una piccola scheda di valutazione che puoi riusare dopo ogni rilascio:

• p95 e p99 della latenza delle richieste durante steady state e durante un burst
• connessioni totali massime (client-side e server-side)
• segnali di tempo in coda (waiting for a free connection)
• tasso di errori e conteggio timeout
• throughput al punto in cui la latenza comincia a salire rapidamente

Col tempo questo trasforma la capacity planning in qualcosa di ripetibile invece che in un azzardo.

Checklist rapida e prossimi passi

Prima di toccare le dimensioni dei pool, scrivi un numero: il tuo connection budget. È il numero massimo sicuro di connessioni Postgres attive per questo ambiente (dev, staging, prod), inclusi job in background e accesso admin. Se non sai dirlo, stai facendo supposizioni.

Una checklist rapida:

• Imposta un max esplicito in Go e assicurati che (istanze x MaxOpenConns) rientri nel budget (o nel cap di PgBouncer).
• Imposta timeout così “aspettare per sempre” non nasconde problemi fino a uno spike.
• Se usi PgBouncer, scegli la modalità di pooling che corrisponde al tuo uso dello stato di sessione.
• Evita lifetime di connessione molto corti che causano reconnect costanti.
• Conferma che max_connections e eventuali connessioni riservate siano allineate col tuo piano.

Piano di rollout che rende il rollback facile:

1. Applica i cambiamenti in staging sotto un load test che replica la concorrenza e il mix read/write di produzione.
2. Rilascia in produzione a piccoli passi (sottoinsieme di istanze o un servizio alla volta).
3. Monitora p95 latency, pool wait time, errori e conteggi di connessioni Postgres attraverso almeno una finestra di picco.
4. Se p95 sale o il pool wait spicca, rollback e abbassa la concorrenza o i limiti del pool.

Se stai costruendo e ospitando un'app Go + PostgreSQL su Koder.ai (koder.ai), Planning Mode può aiutarti a mappare la modifica e cosa misurerai, e snapshot più rollback rendono più semplice revertare se la tail latency peggiora.

Passo successivo: aggiungi una misura prima del prossimo salto di traffico. “Tempo trascorso in attesa di una connessione” nell'app è spesso la più utile, perché mostra pressione del pooling prima che gli utenti la percepiscano.