Extension Postgres pg_graphql, opt-in par projet et désactivée par défaut. Une fois activée, elle expose le même schéma que votre API REST — RLS et rôles hérités, aucune authentification GraphQL séparée — via le proxy RPC générique déjà existant, pas une route dédiée.
5 min de lecture·Niveau intermédiaire·Révisé le 15 août 2026
Une deuxième façon d’interroger le même schéma, pas un service séparé
GraphQL n'est pas une route ou un service HTTP à part sur le gateway : c'est l'extension Postgres pg_graphql (Supabase), qui génère automatiquement un schéma GraphQL à partir de votre schéma SQL réel. Ce que vous activez concrètement, en tant que développeur, c'est une deuxième façon d'interroger le même schéma que votre API REST — pas un backend GraphQL distinct avec sa propre authentification ou ses propres permissions.
Info
Désactivé par défaut, pour tous les projets. Aurabase l'active uniquement sur demande explicite, par projet — jamais automatiquement pour l'ensemble de vos projets. Voir la doc officielle de pg_graphql pour la syntaxe de requête complète (filtres, tri, pagination par curseur, mutations).
Activer GraphQL sur un projet pose, en une seule transaction, l'extension pg_graphql et une fonction "<schéma_projet>".graphql(query, variables, operationName, extensions) dans votre schéma tenant. Cette fonction est ensuite appelable exactement comme n'importe quelle fonction Postgres — via le proxy RPC générique déjà documenté sur /docs/api/database/rpc. Il n'existe aucune route /graphql dédiée sur le gateway.
cycle d’une activation
TEXT
ACTIVATION ────▶ POST .../graphql/enable ou aura projects graphql-enable
ENQUEUE ────▶ job "graphql_enable" enfilé (idempotent, no-op si déjà en vol)
DDL ────▶ CREATE EXTENSION pg_graphql + fonction wrapper + GRANTs, 1 SEULE transaction
FLAG ────▶ projects.graphql_enabled = true, posé SEULEMENT après succès complet
REQUÊTE ────▶ POST /v1/db/{project_id}/rpc/graphql, comme n’importe quel autre RPC
Astuce
La transaction d'activation est tout ou rien : en cas d'échec sur n'importe laquelle des étapes (extension, fonction, GRANTs), tout est annulé (ROLLBACK) et graphql_enabled reste à false — jamais de wrapper posé à moitié.
pg_graphql introspecte votre schéma Postgres et expose chaque table comme un type GraphQL (convention Relay : <table>Collection, edges, node) — aucun SDL à écrire ou maintenir à la main.
§ génération schéma
SECURITY INVOKER — RLS héritée
La fonction wrapper posée dans votre schéma tourne avec les privilèges de l'appelant (aura_anon / aura_authenticated / aura_service_role) : les policies RLS s'appliquent exactement comme pour une requête REST.
§ sécurité
Introspection désactivée par défaut
{ __schema { ... } } échoue tant qu'elle n'est pas explicitement réactivée par schéma — posture RLS-first cohérente avec le reste de la plateforme.
§ introspection
Activation opt-in, idempotente
POST .../graphql/enable (JWT console) ou aura projects graphql-enable (CLI) enfilent un job de provisioning ; jamais activé par défaut, ni pour un projet ni pour l'ensemble des projets.
§ activation
Disponible sur tous les paliers Postgres
Fonctionne sur la base de votre projet, qu'elle vive sur le cluster PostgreSQL de votre organisation ou sur un cluster entièrement dédié (Enterprise) : l'image Postgres embarque pg_graphql, activation validée de bout en bout (extension, wrapper RLS, requête réelle).
§ disponibilité
Réservé aux projets Postgres
Un projet moteur MongoDB refuse l'activation (GRAPHQL_UNSUPPORTED_ENGINE) — pg_graphql est une extension Postgres, sans équivalent sur le moteur secondaire.
# Idempotent : un appel répété sur un projet déjà activé ne recrée rien.
aura projects graphql-enable <project_id>
Astuce
L'activation (CLI ou REST) répond avec le projet à jour, champ graphql_enabled inclus. Pour la syntaxe complète des requêtes (filtres par type de colonne, tri orderBy, pagination par curseur first/after, mutations insertInto<Table>Collection...), voir la référence API officielle pg_graphql.
Il n'existe pas d'endpoint /v1/db/{project_id}/graphql. Une fois activé, GraphQL s'interroge exclusivement via le proxy RPC générique (POST /v1/db/{project_id}/rpc/graphql), le même mécanisme que n'importe quelle fonction Postgres invoquée par aura.db.rpc().
