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.
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.
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 }.
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)
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 (
<table>Collection,edges,node) avec des colonnes SQLsnake_casefléchies encamelCasepar 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é avecUnknown 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) etinflect_names(created_at→createdAt, activé par défaut). La recette pg_graphqlCOMMENT ON SCHEMA … @graphql(...)ne fonctionne pas à partir d'un projet (votre rôle n'est pas propriétaire du schéma et/rawrefuse les littérauxE'…') : utilisezaura projects graphql-configouPATCH …/graphql/configà la place, voir Ajuster les paramètres. - Activation opt-in, idempotente.
POST .../graphql/enable(console JWT) ouaura 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#
# 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
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).
# 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.
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#
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#
- Base de données
Postgres géré, extensions activées, RLS — le schéma exposé par pg_graphql.
- Appeler une fonction Postgres
Le proxy RPC générique (/rpc/{function}) utilisé par les requêtes GraphQL.
- Sécurité et RBAC
RLS, rôles anon/authenticated/service_role — le modèle hérité tel quel par GraphQL.
- CLI
aura project graphql-enable et le reste des commandes du projet.