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 toute la flotte. 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 pour un projet ni pour la flotte.
§ activation
Tier dédié non couvert à ce jour
Fonctionne aujourd'hui uniquement sur le Postgres partagé : l'image des instances CNPG dédiées n'embarque pas encore pg_graphql — l'activation y échoue proprement, sans jamais poser graphql_enabled à true.
§ limitation
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.
L'image Postgres utilisée par les instances CNPG dédiées (TENANT_POSTGRES_IMAGE, y compris en production) est l'image communautaire stock de CloudNativePG, qui n'embarque pas pg_graphql. Activer GraphQL sur un projet dédié échoue proprement — le job de provisioning passe en erreur explicite, graphql_enabled n'est jamais posé à true — en attendant la publication d'une image CNPG compatible. Seul le Postgres partagé (offre flotte) supporte GraphQL aujourd'hui.
Aucune route HTTP dédiée
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().
