PostgREST: benchmark e limiti reali nella produzione

Un test di throughput HTTP su PostgREST misura principalmente Postgres, raramente PostgREST. Il server è un sottile strato di traduzione davanti alla base. Nella stragrande maggioranza dei carichi reali, il tempo di risposta è dominato dalla query SQL eseguita, non dal processo che l'ha generata.

Il progetto PostgREST mantiene un repository dedicato per questo argomento, PostgREST/postgrest-benchmark su GitHub, che tiene traccia delle variazioni di throughput da un rilascio all'altro anziché pubblicare una cifra di marketing isolata. Non l'abbiamo né eseguito né ripubblicato qui. I risultati dipendono dall'hardware, dalle dimensioni dello schema e dallo scenario testato, esattamente le variabili che il nostro protocollo di benchmark richiede che siano documentate prima di citare una cifra.

Sotto PostgREST, c'è pgbench che misura il livello che conta davvero: il tempo di transazione SQL sotto carico simultaneo. Questo è lo strumento di benchmark ufficiale di PostgreSQL (postgresql.org/docs/current/pgbench.html, accesso il 24 agosto 2026). Invece di riprodurre qui questo protocollo, questo articolo documenta quattro limitazioni architettoniche concrete di PostgREST in produzione, ciascuna verificata nel codice sorgente Aurabase o nella documentazione ufficiale del progetto.

Ogni progetto del motore Aurabase Postgres riceve due repliche PostgREST dedicate, co-localizzate con il suo cluster. Il manifest Kubernetes che li distribuisce imposta risorse modeste.

Ciò che realmente consumano queste repliche non è la CPU: sono connessioni al primario Postgres. Ogni istanza PostgREST si connette direttamente al primario (-rw), senza passare attraverso il pooler PgBouncer distribuito per il tenant. Questa scelta è già dettagliata nel nostro articolo sulla compatibilità PostgREST: il meccanismo di ricaricamento dello schema LISTEN/NOTIFY richiede una connessione persistente, incompatibile con un pooler in modalità transazione. Cosa aggiunge questo articolo: quanto costa effettivamente, in termini di connessioni, e dove raggiunge i picchi.

La dimensione di questo pool per replica (PGRST_DB_POOL) varia deliberatamente a seconda del livello del progetto, verificato in k8s_tenant.rs, la funzione che crea il manifest PostgREST per ciascun progetto:

# Impronta digitale delle connessioni per replica sul primario.
env:
  - { name: PGRST_DB_POOL, value: "PGRST_DB_POOL_VALUE" }  # 10 (dedicati) o 2 (condivisi)

A livello dedicato, il vincolo è allentato: un progetto ha il proprio cluster CNPG, quindi il proprio max_connections, senza vicini da risparmiare. Sul piano condiviso, più progetti della stessa organizzazione condividono un unico cluster: è questo contesto che rende decisivo il budget delle connessioni, sviluppato nella sezione successiva.

Su un cluster Postgres condiviso, non è il throughput HTTP a limitare il numero di progetti attivi contemporaneamente. Questo è il numero di connessioni che le loro istanze PostgREST mantengono aperte sul primario, rispetto alle max_connectionsdisponibili.

Aurabase ricava questo budget direttamente dai limiti effettivi del cluster, controllati in fleet.rs: (max_connections − réserve superuser/CNPG − connexions réservées au pooler) ÷ connexions par projet éveillé, minimo a 1. La riserva fissa è di 10 connessioni (superutente, gestore di istanze CNPG, esportatore di metriche, margine di amministrazione del provisioner). Sui difetti consegnati (pool di 2 per replica, 2 repliche o 4 connessioni per progetto risvegliato), il calcolo fornisce tre budget diversi a seconda del livello di dimensionamento del cluster.

Fonte: derivato da fleet.rs::derive_wake_budget e wake_budget_for_org_plan, codice Aurabase, riletto il 24 agosto 2026.

Questo budget non è una quota di progetti posseduti: un'organizzazione team può contenere 50 progetti, la maggior parte dei quali sono dormienti. Questo è un limite di concorrenza: il numero di progetti che possono mantenere connessioni aperte contemporaneamente sul primario. Un risveglio oltre il budget non fallisce, viene rinviato fino a quando un progetto fratello non torna a dormire, controllato nello stesso file. L'argomento del dimensionamento stesso di max_connections è approfondito nel nostro articolo sull'ottimizzazione di max_connectionse sul compromesso dedicato/mutualizzato nel suo insieme in base dedicata e condivisa.

La richiesta di un totale esatto costringe Postgres a contare le righe visibili del risultato filtrato con ogni query, un costo che cresce con la tabella, non un'operazione gratuita.

PostgreSQL non mantiene alcun contatore di righe indicizzate pronto all'uso. In MVCC, la visibilità di una riga dipende dalla transazione che la legge. Un COUNT(*) esatto deve quindi visitare le righe candidate anziché leggere un valore precalcolato. Questa è una limitazione strutturale ben documentata nell'ecosistema Postgres, compresi i fornitori di analisi come ClickHouse, che confrontano i propri contatori approssimativi con il comportamento transazionale di Postgres.

# Costoso su una tabella di grandi dimensioni: forza una scansione MVCC del risultato filtrato
curl "https://<gateway>/v1/db/<project_id>/orders?status=eq.paid" \
  -H "apikey: <clé>" -H "Prefer: count=exact"

# Alternative meno costose, documentate da PostgREST
  -H "Prefer: count=planned"   # stima tramite pianificatore
  -H "Prefer: count=estimated" # pianificato oltre una soglia, esattamente sotto

PostgREST documenta queste tre strategie di conteggio in modo nativo (postgrest.org, accesso il 24 agosto 2026). La strategia exact garantisce il totale al prezzo della scansione. planned restituisce una stima quasi gratuita dal query planner. estimated passa automaticamente tra i due in base a una soglia. La scelta non è cosmetica: un'impaginazione che richiede count=exact su una tabella di diversi milioni di righe paga questa scansione su ogni pagina, anche quando l'utente non consulta mai l'ultima.

Un limite di riga può troncare una risposta PostgREST senza alcuna indicazione nel corpo o nelle intestazioni, a meno che non venga richiesto esplicitamente un totale esatto. L'abbiamo misurato in condizioni reali su un'istanza Aurabase dedicata, non scontata.

Su una tabella di test a 10 righe con PGRST_DB_MAX_ROWS=5, PostgREST v12.2.3 esegue esattamente la stessa intestazione Content-Range per due situazioni molto diverse:

Senza count=exact, la risposta di 5 righe è indistinguibile da una tabella che in realtà ne conterrebbe solo 5: Content-Range: 0-4/* descrive le righe renderizzate, mai il limite applicato. Il limite effettivo in effetti non appare da nessuna parte in questo caso, misurato direttamente sul percorso PostgREST dell'SDK Aurabase.

PostgREST mantiene lo schema Postgres in memoria all'avvio. Dopo un DDL (crea tabella, aggiungi colonna), questa cache deve essere ricaricata prima che la nuova route risponda e questo ricaricamento è asincrono.

Una scrittura che arriva in questa finestra potrebbe ricevere un transitorio 404 (cache non ancora aggiornata), anche se la tabella esiste effettivamente sul lato Postgres. Il gateway Aurabase lo assorbe con un ciclo di tentativi limitato, verificato in postgrest_proxy.rs: fino a 8 tentativi, backoff crescente (250 ms più 100 ms per tentativo), 3,5 secondi cumulativi nel caso peggiore. Questo meccanismo influisce solo sulle scritture, mai sulle letture.

Per una distribuzione PostgREST self-hosted, la lezione è di carattere generale. Ogni percorso DDL nell'applicazione dovrebbe attivare il ricaricamento, tramite NOTIFY o un segnale SIGUSR1 al processo. In caso contrario, una migrazione produce un picco di latenza p99 mascherato da errori intermittenti subito dopo la distribuzione.

Le quattro limitazioni qui documentate condividono una cosa in comune: nessuna viene rilevata in un test di throughput HTTP isolato, ma tutte e quattro determinano se una distribuzione PostgREST si adatta alla produzione.

• Budget di connessione: limita il numero di tenant attivi contemporaneamente su un cluster condiviso, indipendentemente dal throughput per tenant.
• Costo del COUNT esatto: cresce con la tabella, non con il carico; viene bypassato con planned/estimated.
• Troncamento silenzioso: un limite di riga configurato correttamente può comunque interrompere il paging scarsamente strumentato.
• Ricarica dello schema: una finestra di latenza dopo ogni migrazione, limitata se il segnale di ricarica è ben cablato, illimitata altrimenti.

Sia che tu scelga tra PostgREST self-hosted, un livello GraphQL in stile Hasura o un'API personalizzata, questi quattro assi rappresentano un punto di confronto migliore rispetto a una cifra req/s isolata. Guarda il nostro confronto PostgREST vs Hasura vs API personalizzata. La scelta del pooler che si trova di fronte al tuo database è altrettanto importante: il nostro confronto PgBouncer vs Supavisor vs PgCat spiega in dettaglio perché PostgREST non può passare attraverso un pooler in modalità transazione.

PostgREST non si rompe quasi mai sotto il solo carico HTTP: la sua architettura è troppo semplice per questo. Ciò che interrompe la produzione è ciò che la circonda: quante connessioni tengono aperte le sue repliche, quanto costa un totale esatto. Ciò include anche se un troncamento rimane visibile e quanto tempo dura la finestra dopo una migrazione.

Queste quattro limitazioni non sono specifiche di Aurabase: si applicano a qualsiasi distribuzione PostgREST, self-hosted o gestita. Ciò che questo codice mostra è come una distribuzione multi-tenant li renda espliciti anziché lasciarli sorprendenti in produzione.