Compatibilità PostgREST: cosa copre e alternative

PostgREST è un server web autonomo che trasforma un database PostgreSQL esistente in un'API REST, direttamente dal suo schema. Nessun livello applicativo da scrivere: tabelle, viste e funzioni diventano percorsi e le autorizzazioni SQL (ruoli e policy RLS) diventano il livello di autorizzazione.

Concretamente, PostgREST copre cinque funzionalità che emergono in quasi tutte le valutazioni:

• Filtraggio orizzontale — una trentina di operatori (eq, gt, like, ilike, in, is, cs, ov, fts...) direttamente in stringa di interrogazione.
• Filtraggio verticale e incorporamento — ?select= proietta colonne e incorpora relazioni tramite chiave esterna, ad esempio customer:customers(email).
• RPC — un POST /rpc/{fonction} chiama direttamente una funzione SQL, che diventa un endpoint.
• RLS guidato da JWT — PostgREST cambia il ruolo Postgres attivo in base al token ricevuto (SET LOCAL ROLE), in modo che le policy vengano applicate così come sono, senza logica di autorizzazione duplicata sul lato dell'applicazione.
• OpenAPI autogenerata — la specifica è dedotta dallo schema esposto, senza un file da mantenere manualmente.

curl "https://<gateway>/v1/db/<project_id>/orders \
  ?select=id,total,customer:customers(email) \
  &status=eq.paid \
  &order=created_at.desc" \
  -H "apikey: <votre-cle-api>"

Una singola richiesta HTTP filtra gli ordini pagati, incorpora l'e-mail del cliente tramite chiave esterna e ordina per data, senza che un singolo percorso debba essere scritto a mano.

L'RPC segue la stessa logica: una funzione SQL già scritta nel database diventa un endpoint POST, con i suoi argomenti passati in JSON.

curl -X POST "https://<gateway>/v1/db/<project_id>/rpc/monthly_revenue" \
  -H "apikey: <votre-cle-api>" \
  -H "Content-Type: application/json" \
  -d '{"year": 2026, "month": 8}'

Questo principio (lo schema Postgres è l'unica fonte di verità dell'API) è ciò che rende PostgREST prevedibile: ogni cambiamento di comportamento passa attraverso una migrazione SQL, mai attraverso un livello applicativo separato che potrebbe derivare dallo schema reale. Il progetto è open source, sviluppato su GitHub, indipendente da qualsiasi particolare provider BaaS.

PostgREST risolve il livello CRUD. Non risolve il resto del backend dell'applicazione. Quattro carenze si verificano sistematicamente tra i team che lo adottano da soli.

• Autenticazione: nessuna emissione JWT o gestione utente integrata. È necessario crearlo in SQL o delegarlo a un servizio esterno.
• Archiviazione file — nessuno. Resta da collegare separatamente un bucket S3 o equivalente.
• Tempo reale — PostgREST risponde a richieste HTTP una tantum, non invia alcun evento.
• Connection Pooler — PostgREST stesso si connette a Postgres, ma non integra alcun pooler avanzato. Su larga scala, gestirlo diventa una decisione operativa a sé stante: un pooler in modalità transazione classica entra in conflitto con il meccanismo di ricaricamento dello schema PostgREST (vedi sotto come Aurabase risolve questo compromesso).

Una conseguenza pratica merita di essere detta chiaramente: senza autenticazione, le tue policy RLS diventano l’unico confine di sicurezza tra un cliente anonimo e i tuoi dati. Una policy scritta male sul ruolo anon non viene superata da un livello applicativo aggiuntivo: non ce n'è.

Su un progetto del motore Aurabase Postgres, il motore predefinito, il gateway instrada ciascuna richiesta CRUD direttamente a un'istanza PostgREST v12.2.8 dedicata a questo progetto, due repliche, co-localizzate con il cluster Postgres del tenant. Questa non è una compatibilità approssimativa: è lo stesso binario upstream PostgREST, con gli stessi operatori, lo stesso incorporamento, lo stesso RPC, lo stesso RLS guidato da JWT.

Su un progetto del motore MongoDB, la storia è diversa. MongoDB non ha equivalenti a PostgREST: queste richieste vengono instradate a un servizio interno Aurabase, che reimplementa un sottoinsieme delle stesse convenzioni - nomi degli operatori identici, sintassi ?select= con incorporamento, intestazioni Prefer e Content-Range - ma su un motore di documenti, non relazionale. Questo livello ha le sue limitazioni: un incorporamento richiesto nella rappresentazione restituita da una mutazione viene esplicitamente negato anziché ignorato silenziosamente e non esiste un percorso RPC equivalente alle funzioni SQL.

Un dettaglio tecnico contrasta con l'intuizione: ogni istanza PostgREST dedicata rimane direttamente connessa al Postgres primario, senza passare attraverso il pooler PgBouncer distribuito per questo tenant. Motivo presunto: la modalità di pooling delle transazioni interromperebbe il ricaricamento dello schema PostgREST, che si basa su LISTEN/NOTIFY — una connessione persistente, incompatibile con un pool che ricicla la connessione per ogni transazione.

Un altro dettaglio utile in produzione: un progetto inattivo può essere messo in pausa per risparmiare risorse. La prima richiesta su un progetto dormiente ne attiva la riattivazione e riceve un 503 con un ritardo tra i tentativi, il tempo necessario affinché l'istanza PostgREST dedicata ritorni attiva: un presunto compromesso tra costo e latenza a freddo, non un incidente nascosto.

PostgREST ha un utilizzo chiaro: lo schema Postgres è la fonte della verità e il team vuole evitare di scrivere manualmente un livello CRUD. A parte questo caso specifico, esistono diverse famiglie di alternative a seconda di ciò che si desidera aggiungere: dal nulla (nudo self-hosted) a un backend completo pronto all'uso.

La tabella seguente confronta ciò che ciascuna opzione copre in modo nativo e ciò che lascia esplicitamente a te, senza giudizi di valore sull'architettura scelta da ciascun progetto.

Un punto spesso sottovalutato quando si sceglie "self-hosted": PostgREST stesso rimane leggero da eseguire, ma le operazioni di produzione (aggiornamento della versione, alta disponibilità, associazione con un pooler, monitoraggio) rimangono interamente sotto la tua responsabilità: è questo lavoro operativo, non il software, che le piattaforme gestite assorbono.

Per un confronto dettagliato tra gli approcci GraphQL — pg_graphql, Hasura e PostGraphile — vedi il nostro articolo dedicato all'API GraphQL su Postgres.

Quattro situazioni si verificano più spesso. La scelta giusta dipende principalmente da ciò che sei disposto a montare e mantenere da solo.

• Vuoi solo un'API REST su uno schema Postgres esistente, nient'altro. PostgREST self-hosted è sufficiente: fa esattamente quello che fa e non è necessario installare nient'altro.
• Hai bisogno di autenticazione, spazio di archiviazione e tempo reale aggiuntivi e sei pronto per assemblare diversi servizi. Supabase, o PostgREST accompagnato dal tuo stack di applicazioni, soddisfa questa esigenza.
• Preferisci GraphQL a REST. Hasura o PostGraphile coprono questo terreno: una scelta architetturale diversa, non un sostituto diretto per PostgREST.
• Desideri un backend Postgres completo senza unire più servizi separati. Questo è l'angolo che la nostra architettura Rust unificata documenta: vero PostgREST per il livello CRUD, circondato nativamente da funzioni di autenticazione, archiviazione, tempo reale e edge.