GraphQL
Postgres Erweiterung pg_graphql, Opt-in pro Projekt und standardmäßig deaktiviert. Sobald es aktiviert ist, stellt es dasselbe Schema wie Ihre REST-API bereit – erbt RLS und Rollen ohne separate GraphQL-Authentifizierung – über dedizierte /graphql-Routen oder den generischen RPC-Proxy.
Eine zweite Möglichkeit, dasselbe Schema abzufragen, nicht einen separaten Dienst#
GraphQL wird direkt von der Erweiterung Postgres pg_graphql in Ihrer Mandantendatenbank unterstützt und generiert ein GraphQL-Schema aus Ihren SQL-Tabellen, -Ansichten und -Beziehungen. Durch die Aktivierung wird eine zweite Abfrageoberfläche über dasselbe Postgres-Schema wie Ihre REST-API hinzugefügt – und erbt genau dieselben RLS-Richtlinien und -Rollen, ohne einen separaten GraphQL-Server oder eine separate Authentifizierungsebene.
Standardmäßig für alle Projekte deaktiviert. Aurabase aktiviert pg_graphql nur bei expliziter Zustimmung pro Projekt. Die vollständige Abfrage, Filter, Cursor-Paginierung und Mutationssyntax finden Sie in den offiziellen Dokumenten zu pg_graphql.
Ein SQL-Resolver, der auf /graphql und /rpc/graphql verfügbar ist#
Durch die Aktivierung von GraphQL für ein Projekt wird pg_graphql installiert und "<project_schema>".graphql(query, variables, operationName, extensions) in einer einzigen Transaktion erstellt. In einer Projekt-Subdomäne werden Anfragen an POST /graphql, POST /graphql/v1, POST /v1/graphql, POST /v1/graphql/v1 und POST /v1/db/{project_id}/graphql (sowie POST /v1/db/{project_id}/rpc/graphql) an pg_graphql weitergeleitet und geben die Standard-GraphQL-JSON-Nutzlast { "data": ..., "errors": ... } direkt ohne den REST-Wrapper { data, meta } zurück.
ACTIVATION ────▶ POST .../graphql/enable oder Aura-Projekte graphql-enable
ENQUEUE ────▶ Job „graphql_enable“ in der Warteschlange (idempotent, no-op, wenn bereits aktiviert)
DDL ────▶ CREATE EXTENSION pg_graphql + Wrapper-Funktion + GRANTs, 1 einzelne Transaktion
FLAG ────▶ project.graphql_enabled = true, wird nur nach vollständigem Transaktions-Commit gesetzt
QUERY ────▶ POST /graphql oder /v1/db/{project_id}/graphql (gibt rohen GraphQL-JSON zurück)
Die Aktivierungstransaktion ist atomar: Wenn ein Schritt (Erweiterung, Wrapper-Funktion oder GRANTs) fehlschlägt, wird alles zurückgesetzt und graphql_enabled bleibt false.
Welche Aktivierung wird eingerichtet?#
- Automatisch generiertes Schema. pg_graphql untersucht Ihr Postgres-Schema und stellt jede Tabelle als Relay-GraphQL-Typ (
<table>Collection,edges,node) mit SQL-Spaltensnake_casebereit, die standardmäßig incamelCaseumgewandelt werden – kein SDL, das manuell geschrieben werden muss. - SECURITY INVOKER – Geerbt RLS. Die Wrapper-Funktion wird mit den Berechtigungen des Aufrufers (
aura_anon/aura_authenticated/aura_service_role) ausgeführt und erzwingt genau die gleichen RLS-Richtlinien wie REST-Anfragen. - Drei Einstellungen, die Sie ändern können, atomar angewendet.
introspection(standardmäßig deaktiviert:{ __schema { ... } }wird mitUnknown field "__schema"abgelehnt, sodass GraphiQL und Apollo-Codegen das Schema erst erkennen können, wenn Sie es aktivieren),max_rows(pro Sammlung zurückgegebene Zeilen, 1 bis 10000, Standard 1000) undinflect_names(created_at→createdAt, aktiviert von Standardeinstellung). Das Rezept pg_graphqlCOMMENT ON SCHEMA … @graphql(...)funktioniert nicht in einem Projekt (Ihre Rolle ist nicht Eigentümer des Schemas und/rawlehntE'…'-Literale ab): Verwenden Sie stattdessenaura projects graphql-configoderPATCH …/graphql/config, siehe Optimieren Sie die Einstellungen. - Opt-in-Aktivierung, idempotent.
POST .../graphql/enable(Konsole JWT) oderaura projects graphql-enable --wait(CLI) sendet den Bereitstellungsauftrag und kehrt mit--waitzurück, sobald GraphQL tatsächlich aktiviert ist; nie automatisch eingeschaltet. - Verfügbar auf allen Postgres-Stufen. Funktioniert unabhängig davon, ob Ihr Projekt auf einem Postgres-Organisationscluster oder einem dedizierten Unternehmenscluster ausgeführt wird. durchgängig validiert (Erweiterung, RLS-Wrapper, echte Abfrage).
- Nur Postgres Projekte. Ein MongoDB-Projekt verweigert die Aktivierung (
GRAPHQL_UNSUPPORTED_ENGINE).
Aktivieren, dann abfragen#
# Idempotent: Ein wiederholter Aufruf eines bereits aktivierten Projekts ist ein No-Op.
# --wait kehrt zurück, sobald GraphQL tatsächlich aktiviert ist (die Aktivierung ist ein Hintergrundjob).
aura projects graphql-enable <project_id> --wait
Activation responds with the updated project (graphql_enabled: true). Notice column inflection (created_at → createdAt): see the official pg_graphql API reference for filters, orderBy, cursor pagination (first/after), and mutations (insertInto<Table>Collection).
Optimieren Sie die Einstellungen: Selbstbeobachtung, maximale Zeilenzahl, Namensflexion#
pg_graphql liest seine Einstellungen aus einem Kommentar zum Schema Ihres Projekts. Nur der Schemabesitzer kann es schreiben, sodass die Plattform dies für Sie in einer Transaktion erledigt, wenn Sie darum bitten. Eine Änderung ist idempotent (das Abfragen dessen, was bereits angewendet wurde, bewirkt nichts) und begrenzt (max_rows außerhalb von 1–10000 wird abgelehnt, bevor etwas in die Warteschlange gestellt wird).
# Zeigt die gültigen Einstellungen an
aura projects graphql-config <project_id>
# Aktivieren Sie die Selbstbeobachtung (GraphiQL, graphql-codegen, Apollo) und warten Sie, bis sie angewendet wird
aura projects graphql-config <project_id> --introspection on --wait
# Begrenzen Sie Sammlungen auf 100 Zeilen und behalten Sie die SQL-Namen bei, wie sie sind
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait
state sagt die Wahrheit über die Änderung: pending, während sie angewendet wird (mit pending_config), failed, wenn dies nicht möglich ist (die Einstellungen in config sind dann weiterhin gültig), applied andernfalls. GraphQL muss zuerst aktiviert werden (andernfalls GRAPHQL_NOT_ENABLED) und eine zweite Änderung, während Antworten ausstehen GRAPHQL_CONFIG_PENDING: Versuchen Sie es in ein paar Sekunden erneut.
Wenn introspection aktiviert ist, kann jeder, der über den öffentlichen Schlüssel des Projekts verfügt, jede Tabelle und Spalte auflisten, die GraphQL verfügbar macht (RLS schützt weiterhin die Zeilen). Schalten Sie es für die Entwicklung ein und für die Produktion wieder aus, wenn die Form Ihres Schemas empfindlich ist.
Aufmerksamkeitspunkte#
Standardmäßig wendet pg_graphql SQL-Namen snake_case auf GraphQL camelCase um (created_at wird zu createdAt, Tabelle blog_posts wird zu blogPostsCollection). Nach DDL-Änderungen lädt PostgREST seinen Schema-Cache innerhalb von Sekunden neu, sodass sowohl /graphql als auch /rpc/graphql aktualisierte Felder verfügbar machen.
Um weiter zu gehen#
- Datenbank
Postgres verwaltet, Erweiterungen aktiviert, RLS – das Schema, das pg_graphql verfügbar macht.
- Rufen Sie eine Postgres-Funktion auf
Der generische RPC-Proxy (/rpc/{function}), der von GraphQL-Abfragen verwendet wird.
- Sicherheit und RBAC
RLS, Rollen anon/authenticated/service_role – das Modell, das unverändert von GraphQL geerbt wird.
- CLI
Aura-Projekte graphql-enable und die restlichen Projektbefehle.