Zum Inhalt springen
Aurabase-Logo
Aurabasis

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.

Erklärung5 Min. gelesenEbene MittelstufeÜberarbeitet am 11.11.2026

Diese Seite wurde automatisch übersetzt. Maßgeblich ist die englische Version.

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.

Infos

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.

Zyklus einer Aktivierungtext
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)
Tipp

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 (&lt;table&gt;Collection, edges, node) mit SQL-Spalten snake_case bereit, die standardmäßig in camelCase umgewandelt 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 mit Unknown 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) und inflect_names (created_at → createdAt, aktiviert von Standardeinstellung). Das Rezept pg_graphql COMMENT ON SCHEMA … @graphql(...) funktioniert nicht in einem Projekt (Ihre Rolle ist nicht Eigentümer des Schemas und /raw lehnt E'…'-Literale ab): Verwenden Sie stattdessen aura projects graphql-config oder PATCH …/graphql/config, siehe Optimieren Sie die Einstellungen.
  • Opt-in-Aktivierung, idempotent. POST .../graphql/enable (Konsole JWT) oder aura projects graphql-enable --wait (CLI) sendet den Bereitstellungsauftrag und kehrt mit --wait zurü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#

graphql-enable.shbash
# 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
Tipp

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).

graphql-config.shbash
# 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.

Selbstbeobachtung legt Ihr Schema offen

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#

Namensflexion und Schema-Neuladen

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#