GraphQL
Postgres estensione pg_graphql, attivazione per progetto e disabilitata per impostazione predefinita. Una volta abilitato, espone lo stesso schema dell'API REST, ereditando RLS e ruoli senza autenticazione GraphQL separata, tramite percorsi /graphql dedicati o proxy RPC generico.
Un secondo modo per interrogare lo stesso schema, non un servizio separato#
GraphQL è alimentato direttamente dall'estensione Postgres pg_graphql all'interno del database del tenant, generando uno schema GraphQL dalle tabelle, viste e relazioni SQL. Abilitandola si aggiunge una seconda superficie di query sullo stesso Postgres schema dell'API REST, ereditando esattamente le stesse policy e ruoli RLS, senza un server GraphQL o un livello di autenticazione separati.
Disabilitato per impostazione predefinita per tutti i progetti. Aurabase attiva pg_graphql solo su consenso esplicito per progetto. Consulta la documentazione ufficiale pg_graphql per query complete, filtri, impaginazione del cursore e sintassi di mutazione.
Un risolutore SQL esposto su /graphql e /rpc/graphql#
L'abilitazione di GraphQL su un progetto installa pg_graphql e crea "<project_schema>".graphql(query, variables, operationName, extensions) in un'unica transazione. Su un sottodominio del progetto, le richieste a POST /graphql, POST /graphql/v1, POST /v1/graphql, POST /v1/graphql/v1 e POST /v1/db/{project_id}/graphql (così come POST /v1/db/{project_id}/rpc/graphql) vengono instradate a pg_graphql e restituiscono il payload standard { "data": ..., "errors": ... } GraphQL JSON direttamente senza REST { data, meta } involucro.
ACTIVATION ────▶ POST .../graphql/enable o progetti aura graphql-enable
ENQUEUE ────▶ job "graphql_enable" in coda (idempotente, no-op se già abilitato)
DDL ────▶ CREATE EXTENSION pg_graphql + funzione wrapper + GRANT, 1 singola transazione
FLAG ────▶ progetti.graphql_enabled = true, impostato solo dopo il commit completo della transazione
QUERY ────▶ POST /graphql o /v1/db/{project_id}/graphql (restituisce GraphQL JSON non elaborato)
La transazione di attivazione è atomica: se qualsiasi passaggio (estensione, funzione wrapper o GRANT) fallisce, tutto viene ripristinato e graphql_enabled rimane false.
Cosa configura l'attivazione#
- Schema generato automaticamente. pg_graphql analizza il tuo schema Postgres ed espone ogni tabella come tipo Relay GraphQL (
<table>Collection,edges,node) con colonne SQLsnake_casedeclinate incamelCaseper impostazione predefinita: nessun SDL da scrivere a mano. - SECURITY INVOKER — Ereditato RLS. La funzione wrapper viene eseguita con i privilegi del chiamante (
aura_anon/aura_authenticated/aura_service_role), applicando esattamente le stesse policy RLS delle richieste REST. - Tre impostazioni che puoi modificare, applicate atomicamente.
introspection(disattivato per impostazione predefinita:{ __schema { ... } }viene rifiutato conUnknown field "__schema", quindi GraphiQL e il codegen Apollo non possono scoprire lo schema finché non lo accendi),max_rows(righe restituite per raccolta, da 1 a 10000, predefinito 1000) einflect_names(created_at→createdAt, attivo per impostazione predefinita). La ricetta pg_graphqlCOMMENT ON SCHEMA … @graphql(...)non funziona da un progetto (il tuo ruolo non possiede lo schema e/rawrifiuta i valori letteraliE'…'): utilizza inveceaura projects graphql-configoPATCH …/graphql/config, vedi Ottimizzare le impostazioni. - Attivazione opt-in, idempotente.
POST .../graphql/enable(console JWT) oaura projects graphql-enable --wait(CLI) invia il processo di provisioning e, con--wait, restituisce una volta che GraphQL è effettivamente abilitato; mai acceso automaticamente. - Disponibile su tutti i livelli Postgres. Funziona sia che il tuo progetto venga eseguito su un cluster Postgres dell'organizzazione o su un cluster Enterprise dedicato; validato end-to-end (estensione, wrapper RLS, query reale).
- Postgres solo progetti. Un progetto MongoDB rifiuta l'attivazione (
GRAPHQL_UNSUPPORTED_ENGINE).
Attiva, quindi interroga#
# Idempotente: una chiamata ripetuta su un progetto già abilitato è una no-op.
# --wait restituisce una volta che GraphQL è effettivamente abilitato (l'attivazione è un lavoro in background).
aura projects graphql-enable <project_id> --wait
L'attivazione risponde con il progetto aggiornato (graphql_enabled: true). Notare l'inflessione della colonna (created_at → createdAt): vedere il riferimento API ufficiale pg_graphql per filtri, orderBy, impaginazione del cursore (first/after) e mutazioni (insertInto<Table>Collection).
Ottimizza le impostazioni: introspezione, numero massimo di righe, inflessione del nome#
pg_graphql legge le sue impostazioni da un commento sullo schema del tuo progetto. Solo il proprietario dello schema può scriverlo, quindi la piattaforma lo fa per te, in un'unica transazione, quando lo chiedi. Una modifica è idempotente (chiedere ciò che è già applicato non fa nulla) e limitata (max_rows esterno a 1–10000 viene rifiutato prima che qualsiasi cosa venga messa in coda).
# Mostra le impostazioni in vigore
aura projects graphql-config <project_id>
# Attiva l'introspezione (GraphiQL, graphql-codegen, Apollo), attendi finché non viene applicata
aura projects graphql-config <project_id> --introspection on --wait
# Limita le raccolte a 100 righe e mantieni i nomi SQL così come sono
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait
state dice la verità sulla modifica: pending mentre viene applicata (con pending_config), failed se non può essere (le impostazioni in config sono ancora quelle in vigore), applied altrimenti. GraphQL deve essere abilitato per primo (GRAPHQL_NOT_ENABLED altrimenti) e una seconda modifica mentre una è in sospeso risponde GRAPHQL_CONFIG_PENDING: riprova tra qualche secondo.
Con introspection attivato, chiunque detenga la chiave pubblica del progetto può elencare ogni tabella e colonna esposta da GraphQL (RLS protegge comunque le righe). Attivalo per lo sviluppo e disattivalo nuovamente per la produzione se la forma del tuo schema è sensibile.
Punti di attenzione#
Per impostazione predefinita, pg_graphql traduce i nomi SQL snake_case in GraphQL camelCase (created_at diventa createdAt, la tabella blog_posts diventa blogPostsCollection). Dopo le modifiche DDL, PostgREST ricarica la cache dello schema in pochi secondi in modo che sia /graphql che /rpc/graphql espongano i campi aggiornati.
Per andare oltre#
- Banca dati
Postgres gestito, estensioni abilitate, RLS: lo schema esposto da pg_graphql.
- Chiama una funzione Postgres
Il proxy RPC generico (/rpc/{function}) utilizzato dalle query GraphQL.
- Sicurezza e RBAC
RLS, ruoli anon/authenticated/service_role — il modello ereditato così com'è da GraphQL.
- CLI
aura proietta graphql-enable e il resto dei comandi del progetto.