Aller au contenu
Logo Aurabase
aurabase

GraphQL

Extension Postgres pg_graphql, opt-in par projet et désactivée par défaut. Une fois activé, il expose le même schéma que votre API REST — héritant de RLS et de rôles sans authentification GraphQL distincte — via des routes /graphql dédiées ou le proxy RPC générique.

Explication5 min de lectureNiveau intermédiaireRévisé le 11 nov. 2026

Cette page a été traduite automatiquement. La version anglaise fait foi.

Une deuxième façon d'interroger le même schéma, pas un service distinct#

GraphQL est alimenté directement par l'extension Postgres pg_graphql dans votre base de données de locataires, générant un schéma GraphQL à partir de vos tables, vues et relations SQL. L'activer ajoute une deuxième surface de requête sur le même schéma Postgres que votre API REST - héritant exactement des mêmes politiques et rôles RLS, sans serveur GraphQL ou couche d'authentification distinct.

Informations

Désactivé par défaut pour tous les projets. Aurabase active pg_graphql uniquement sur opt-in explicite par projet. Consultez la documentation officielle pg_graphql pour connaître la syntaxe complète des requêtes, des filtres, de la pagination du curseur et des mutations.

Un résolveur SQL exposé sur /graphql et /rpc/graphql#

L'activation de GraphQL sur un projet installe pg_graphql et crée "<project_schema>".graphql(query, variables, operationName, extensions) en une seule transaction. Sur un sous-domaine de projet, les requêtes adressées à POST /graphql, POST /graphql/v1, POST /v1/graphql, POST /v1/graphql/v1 et POST /v1/db/{project_id}/graphql (ainsi qu'à POST /v1/db/{project_id}/rpc/graphql) sont acheminées vers pg_graphql et renvoient la charge utile standard { "data": ..., "errors": ... } GraphQL JSON directement sans le wrapper REST { data, meta }.

cycle d'une activationtext
ACTIVATION  ────▶  POST .../graphql/enable ou projets aura graphql-enable
ENQUEUE     ────▶  travail "graphql_enable" en file d'attente (idempotent, sans opération si déjà activé)
DDL         ────▶  CREATE EXTENSION pg_graphql + fonction wrapper + GRANT, 1 seule transaction
FLAG        ────▶  projects.graphql_enabled = true, défini uniquement après la validation complète de la transaction
QUERY       ────▶  POST /graphql ou /v1/db/{project_id}/graphql (renvoie le JSON GraphQL brut)
Astuce

La transaction d'activation est atomique : si une étape (extension, fonction wrapper ou GRANT) échoue, tout est annulé et graphql_enabled reste false.

Quelle activation configure#

  • Schéma généré automatiquement. pg_graphql introspecte votre schéma Postgres et expose chaque table en tant que type Relay GraphQL (&lt;table&gt;Collection, edges, node) avec des colonnes SQL snake_case fléchies en camelCase par défaut — pas de SDL à écrire à la main.
  • INVOKER DE SÉCURITÉ — Hérité de RLS. La fonction wrapper s'exécute avec les privilèges de l'appelant (aura_anon / aura_authenticated / aura_service_role), appliquant exactement les mêmes politiques RLS que les requêtes REST.
  • Trois paramètres que vous pouvez modifier, appliqués de manière atomique. introspection (désactivé par défaut : { __schema { ... } } est refusé avec Unknown field "__schema", donc GraphiQL et Apollo codegen ne peuvent pas découvrir le schéma tant que vous ne l'avez pas activé), max_rows (lignes renvoyées par collection, 1 à 10 000, par défaut 1 000) et inflect_names (created_at → createdAt, activé par défaut). La recette pg_graphql COMMENT ON SCHEMA … @graphql(...) ne fonctionne pas à partir d'un projet (votre rôle n'est pas propriétaire du schéma et /raw refuse les littéraux E'…') : utilisez aura projects graphql-config ou PATCH …/graphql/config à la place, voir Ajuster les paramètres.
  • Activation opt-in, idempotente. POST .../graphql/enable (console JWT) ou aura projects graphql-enable --wait (CLI) distribue la tâche de provisionnement et, avec --wait, revient une fois que GraphQL est réellement activé ; Jamais allumé automatiquement.
  • Disponible sur tous les niveaux Postgres. Fonctionne que votre projet s'exécute sur un cluster d'organisation Postgres ou sur un cluster d'entreprise dédié ; validé de bout en bout (extension, wrapper RLS, requête réelle).
  • Projets Postgres uniquement. Un projet MongoDB refuse l'activation (GRAPHQL_UNSUPPORTED_ENGINE).

Activer, puis interroger#

graphql-enable.shbash
# Idempotent : un appel répété sur un projet déjà activé est un échec.
# --wait revient une fois que GraphQL est réellement activé (l'activation est un travail en arrière-plan).
aura projects graphql-enable <project_id> --wait
Astuce

L'activation répond avec le projet mis à jour (graphql_enabled: true). Remarquez l'inflexion de la colonne (created_at → createdAt) : consultez la référence officielle de l'API pg_graphql pour les filtres, orderBy, la pagination du curseur (first/after) et les mutations (insertInto<Table>Collection).

Ajustez les paramètres : introspection, nombre maximum de lignes, inflexion du nom#

pg_graphql lit ses paramètres à partir d'un commentaire sur le schéma de votre projet. Seul le propriétaire du schéma peut l'écrire, donc la plateforme le fait pour vous, en une seule transaction, lorsque vous le demandez. Un changement est idempotent (demander ce qui est déjà appliqué ne fait rien) et limité (max_rows en dehors de 1 à 10 000 est refusé avant que quoi que ce soit ne soit mis en file d'attente).

graphql-config.shbash
# Afficher les paramètres en vigueur
aura projects graphql-config <project_id>

# Activez l'introspection (GraphiQL, graphql-codegen, Apollo), attendez qu'elle soit appliquée
aura projects graphql-config <project_id> --introspection on --wait

# Limitez les collections à 100 lignes et conservez les noms SQL tels quels
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait

state dit la vérité sur le changement : pending pendant son application (avec pending_config), failed s'il ne pouvait pas l'être (les paramètres dans config sont alors toujours ceux en vigueur), applied sinon. GraphQL doit être activé en premier (GRAPHQL_NOT_ENABLED sinon), et un deuxième changement pendant que l'on est en attente de réponses GRAPHQL_CONFIG_PENDING: réessayez dans quelques secondes.

L'introspection expose votre schéma

Avec introspection activé, toute personne détenant la clé publique du projet peut répertorier toutes les tables et colonnes exposées par GraphQL (RLS protège toujours les lignes). Activez-le pour le développement, puis désactivez-le pour la production si la forme de votre schéma est sensible.

Points d'attention#

Inflexion de dénomination et rechargement de schéma

Par défaut, pg_graphql infléchit les noms SQL snake_case en GraphQL camelCase (created_at devient createdAt, la table blog_posts devient blogPostsCollection). Après les modifications DDL, PostgREST recharge son cache de schéma en quelques secondes afin que /graphql et /rpc/graphql exposent les champs mis à jour.

Pour aller plus loin#