GrafiekQL
Postgres extensie pg_graphql, opt-in per project en standaard uitgeschakeld. Eenmaal ingeschakeld, wordt hetzelfde schema weergegeven als uw REST API – waarbij RLS en rollen worden overgenomen zonder afzonderlijke GraphQL-authenticatie – via speciale /graphql-routes of de generieke RPC-proxy.
Een tweede manier om hetzelfde schema op te vragen, niet een afzonderlijke service#
GraphQL wordt rechtstreeks mogelijk gemaakt door de Postgres pg_graphql extensie in uw tenantdatabase, waardoor een GraphQL-schema wordt gegenereerd op basis van uw SQL-tabellen, weergaven en relaties. Als u dit inschakelt, wordt een tweede queryoppervlak toegevoegd over hetzelfde Postgres schema als uw REST API - waarbij exact hetzelfde RLS beleid en dezelfde rollen worden overgenomen, zonder een afzonderlijke GraphQL-server of auth-laag.
Standaard uitgeschakeld voor alle projecten. Aurabase activeert pg_graphql alleen bij expliciete opt-in per project. Zie de officiële pg_graphql documenten voor de volledige query, filter, cursorpaginering en mutatiesyntaxis.
Een SQL-resolver beschikbaar op /graphql en /rpc/graphql#
Als u GraphQL inschakelt voor een project, wordt pg_graphql geïnstalleerd en wordt "<project_schema>".graphql(query, variables, operationName, extensions) in één enkele transactie aangemaakt. Op een projectsubdomein worden verzoeken aan POST /graphql, POST /graphql/v1, POST /v1/graphql, POST /v1/graphql/v1 en POST /v1/db/{project_id}/graphql (evenals POST /v1/db/{project_id}/rpc/graphql) doorgestuurd naar pg_graphql en retourneren de standaard { "data": ..., "errors": ... } GraphQL JSON-payload rechtstreeks zonder de REST { data, meta }-wrapper.
ACTIVATION ────▶ POST .../graphql/enable of aura-projecten graphql-enable
ENQUEUE ────▶ taak "graphql_enable" in de wachtrij (idempotent, no-op indien al ingeschakeld)
DDL ────▶ MAAK UITBREIDING pg_graphql + wrapperfunctie + SUBSIDIES, 1 enkele transactie
FLAG ────▶ projects.graphql_enabled = true, alleen ingesteld na volledige transactiecommit
QUERY ────▶ POST /graphql of /v1/db/{project_id}/graphql (retourneert onbewerkte GraphQL JSON)
De activeringstransactie is atomair: als een stap (extensie, wrapperfunctie of GRANTs) mislukt, wordt alles teruggedraaid en blijft graphql_enabled false.
Welke activering wordt ingesteld#
- Automatisch gegenereerd schema. pg_graphql onderzoekt uw Postgres-schema en geeft elke tabel weer als een Relay GraphQL-type (
<table>Collection,edges,node) met SQLsnake_case-kolommen standaard verbogen naarcamelCase- geen SDL om met de hand te schrijven. - SECURITY INVOKER — Overgenomen RLS. De wrapperfunctie wordt uitgevoerd met de rechten van de aanroeper (
aura_anon/aura_authenticated/aura_service_role), waarbij exact hetzelfde RLS-beleid wordt afgedwongen als REST-verzoeken. - Drie instellingen die u kunt wijzigen, atomair toegepast.
introspection(standaard uitgeschakeld:{ __schema { ... } }wordt geweigerd metUnknown field "__schema", dus GraphiQL en Apollo codegen kunnen het schema pas ontdekken als je het inschakelt),max_rows(rijen geretourneerd per verzameling, 1 tot 10000, standaard 1000) eninflect_names(created_at→createdAt, ingeschakeld door standaard). Het recept pg_graphqlCOMMENT ON SCHEMA … @graphql(...)werkt niet vanuit een project (uw rol is niet de eigenaar van het schema en/rawweigertE'…'letterlijke waarden): gebruik in plaats daarvanaura projects graphql-configofPATCH …/graphql/config, zie De instellingen afstemmen. - Opt-in activering, idempotent.
POST .../graphql/enable(console JWT) ofaura projects graphql-enable --wait(CLI) verzendt de inrichtingstaak en keert met--waitterug zodra GraphQL daadwerkelijk is ingeschakeld; nooit automatisch ingeschakeld. - Beschikbaar op alle Postgres-niveaus. Werkt ongeacht of uw project draait op een Postgres-organisatiecluster of een speciaal Enterprise-cluster; end-to-end gevalideerd (extensie, RLS wrapper, echte query).
- Alleen Postgres projecten. Een MongoDB-project weigert activering (
GRAPHQL_UNSUPPORTED_ENGINE).
Activeer en vraag vervolgens#
# Idempotent: een herhaalde oproep op een reeds ingeschakeld project is een no-op.
# --wait keert terug zodra GraphQL daadwerkelijk is ingeschakeld (de activering is een achtergrondtaak).
aura projects graphql-enable <project_id> --wait
Activering reageert met het bijgewerkte project (graphql_enabled: true). Let op de kolomverbuiging (created_at → createdAt): zie de officiële pg_graphql API-referentie voor filters, orderBy, cursorpaginering (first/after) en mutaties (insertInto<Table>Collection).
Stem de instellingen af: introspectie, maximale rijen, naamverbuiging#
pg_graphql leest zijn instellingen uit een opmerking over het schema van uw project. Alleen de schema-eigenaar kan het schrijven, dus het platform doet het voor u, in één transactie, wanneer u daarom vraagt. Een wijziging is idempotent (vragen om wat al is toegepast, doet niets) en begrensd (max_rows buiten 1–10000 wordt geweigerd voordat er iets in de wachtrij wordt geplaatst).
# Toon de actieve instellingen
aura projects graphql-config <project_id>
# Zet introspectie aan (GraphiQL, graphql-codegen, Apollo), wacht tot het wordt toegepast
aura projects graphql-config <project_id> --introspection on --wait
# Beperk verzamelingen tot 100 rijen en laat de SQL-namen ongewijzigd
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait
state vertelt de waarheid over de wijziging: pending terwijl deze wordt toegepast (met pending_config), failed als dit niet mogelijk is (de instellingen in config zijn dan nog steeds van kracht), applied anders. GraphQL moet eerst worden ingeschakeld (anders GRAPHQL_NOT_ENABLED) en een tweede wijziging terwijl er één in afwachting is van antwoorden GRAPHQL_CONFIG_PENDING: probeer het over een paar seconden opnieuw.
Als introspection is ingeschakeld, kan iedereen die de openbare sleutel van het project bezit, elke tabel en kolom weergeven die GraphQL openbaar maakt (RLS beschermt nog steeds de rijen). Schakel het in voor ontwikkeling en weer uit voor productie als de vorm van uw schema gevoelig is.
Aandachtspunten#
Standaard verbuigt pg_graphql SQL snake_case namen naar GraphQL camelCase (created_at wordt createdAt, tabel blog_posts wordt blogPostsCollection). Na DDL-wijzigingen laadt PostgREST de schemacache binnen enkele seconden opnieuw, zodat zowel /graphql als /rpc/graphql bijgewerkte velden weergeven.
Om verder te gaan#
- Database
Postgres beheerd, extensies ingeschakeld, RLS — het schema dat pg_graphql blootlegt.
- Roep een Postgres-functie aan
De generieke RPC-proxy (/rpc/{function}) die wordt gebruikt door GraphQL-query's.
- Beveiliging en RBAC
RLS, rollen anon/authenticated/service_role — het model dat wordt geërfd zoals het is door GraphQL.
- CLI
aura projecten graphql-enable en de rest van de projectopdrachten.