GrafoQL
Postgres extensión pg_graphql, habilitada por proyecto y deshabilitada de forma predeterminada. Una vez habilitado, expone el mismo esquema que su API REST (heredando RLS y roles sin autenticación GraphQL separada) a través de rutas /graphql dedicadas o el proxy RPC genérico.
Una segunda forma de consultar el mismo esquema, no un servicio independiente#
GraphQL funciona directamente con la extensión Postgres pg_graphql dentro de su base de datos de inquilinos, generando un esquema GraphQL a partir de sus tablas, vistas y relaciones SQL. Habilitarlo agrega una segunda superficie de consulta sobre el mismo esquema Postgres que su API REST, heredando exactamente las mismas políticas y roles RLS, sin un servidor GraphQL o una capa de autenticación separados.
Deshabilitado de forma predeterminada para todos los proyectos. Aurabase activa pg_graphql solo en caso de suscripción explícita por proyecto. Consulte los documentos oficiales pg_graphql para consultar la sintaxis completa, el filtro, la paginación del cursor y la mutación.
Un solucionador de SQL expuesto en /graphql y /rpc/graphql#
Al habilitar GraphQL en un proyecto, se instala pg_graphql y se crea "<project_schema>".graphql(query, variables, operationName, extensions) en una sola transacción. En un subdominio de proyecto, las solicitudes a POST /graphql, POST /graphql/v1, POST /v1/graphql, POST /v1/graphql/v1 y POST /v1/db/{project_id}/graphql (así como POST /v1/db/{project_id}/rpc/graphql) se enrutan a pg_graphql y devuelven la carga útil estándar { "data": ..., "errors": ... } GraphQL JSON directamente sin el contenedor REST { data, meta }.
ACTIVATION ────▶ POST .../graphql/enable o proyectos aura graphql-enable
ENQUEUE ────▶ trabajo "graphql_enable" en cola (idempotente, no operativo si ya está habilitado)
DDL ────▶ CREAR EXTENSIÓN pg_graphql + función contenedora + SUBVENCIONES, 1 sola transacción
FLAG ────▶ proyectos.graphql_enabled = verdadero, se establece solo después de la confirmación completa de la transacción
QUERY ────▶ POST /graphql o /v1/db/{project_id}/graphql (devuelve GraphQL JSON sin formato)
La transacción de activación es atómica: si algún paso (extensión, función contenedora o GRANT) falla, todo se revierte y graphql_enabled permanece false.
¿Qué configura la activación?#
- Esquema generado automáticamente. pg_graphql realiza una introspección de su esquema Postgres y expone cada tabla como un tipo Relay GraphQL (
<table>Collection,edges,node) con columnas SQLsnake_caseinvertidas encamelCasede forma predeterminada: no hay SDL para escribir a mano. - INVOCADOR DE SEGURIDAD: RLS heredado. La función contenedora se ejecuta con los privilegios de la persona que llama (
aura_anon/aura_authenticated/aura_service_role), aplicando exactamente las mismas políticas RLS que las solicitudes REST. - Tres configuraciones que puedes cambiar, aplicadas atómicamente.
introspection(desactivado de forma predeterminada:{ __schema { ... } }se rechaza conUnknown field "__schema", por lo que GraphiQL y Apollo codegen no pueden descubrir el esquema hasta que lo active),max_rows(filas devueltas por colección, de 1 a 10000, predeterminado 1000) yinflect_names(created_at→createdAt, activado por predeterminado). La receta pg_graphqlCOMMENT ON SCHEMA … @graphql(...)no funciona desde un proyecto (su rol no es propietario del esquema y/rawrechaza los literalesE'…'): utiliceaura projects graphql-configoPATCH …/graphql/configen su lugar; consulte Ajuste la configuración. - Activación voluntaria, idempotente.
POST .../graphql/enable(consola JWT) oaura projects graphql-enable --wait(CLI) envía el trabajo de aprovisionamiento y, con--wait, regresa una vez que GraphQL está realmente habilitado; Nunca se enciende automáticamente. - Disponible en todos los niveles Postgres. funciona ya sea que su proyecto se ejecute en un clúster de organización Postgres o en un clúster empresarial dedicado; validado de un extremo a otro (extensión, contenedor RLS, consulta real).
- Postgres proyectos únicamente. Un proyecto MongoDB rechaza la activación (
GRAPHQL_UNSUPPORTED_ENGINE).
Activar y luego consultar#
# Idempotente: una llamada repetida a un proyecto ya habilitado no es operativa.
# --wait regresa una vez que GraphQL está realmente habilitado (la activación es un trabajo en segundo plano).
aura projects graphql-enable <project_id> --wait
La activación responde con el proyecto actualizado (graphql_enabled: true). Observe la inflexión de la columna (created_at → createdAt): consulte la referencia oficial de la API pg_graphql pg_graphql API para filtros, orderBy, paginación del cursor (first/after) y mutaciones (insertInto<Table>Collection).
Ajuste la configuración: introspección, filas máximas, inflexión de nombre#
pg_graphql lee su configuración de un comentario en el esquema de su proyecto. Solo el propietario del esquema puede escribirlo, por lo que la plataforma lo hace por usted, en una sola transacción, cuando usted lo solicita. Un cambio es idempotente (pedir lo que ya está aplicado no hace nada) y está limitado (max_rows fuera de 1–10000 se rechaza antes de que algo se ponga en cola).
# Mostrar la configuración vigente
aura projects graphql-config <project_id>
# Active la introspección (GraphiQL, graphql-codegen, Apollo), espere hasta que se aplique
aura projects graphql-config <project_id> --introspection on --wait
# Limite las colecciones a 100 filas y mantenga los nombres SQL como están
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait
state dice la verdad sobre el cambio: pending mientras se aplica (con pending_config), failed si no pudo ser (las configuraciones en config siguen siendo las vigentes), applied en caso contrario. GraphQL debe habilitarse primero (GRAPHQL_NOT_ENABLED de lo contrario) y un segundo cambio mientras uno está pendiente de respuestas GRAPHQL_CONFIG_PENDING: vuelva a intentarlo en unos segundos.
Con introspection activado, cualquiera que tenga la clave pública del proyecto puede enumerar todas las tablas y columnas que expone GraphQL (RLS aún protege las filas). Actívelo para desarrollo y desactívelo nuevamente para producción si la forma de su esquema es sensible.
Puntos de atención#
De forma predeterminada, pg_graphql modifica los nombres SQL snake_case a GraphQL camelCase (created_at se convierte en createdAt, la tabla blog_posts se convierte en blogPostsCollection). Después de los cambios de DDL, PostgREST recarga su caché de esquema en segundos para que tanto /graphql como /rpc/graphql expongan los campos actualizados.
para ir más lejos#
- Base de datos
Postgres administrado, extensiones habilitadas, RLS: el esquema que expone pg_graphql.
- Llamar a una función Postgres
El proxy RPC genérico (/rpc/{function}) utilizado por las consultas GraphQL.
- Seguridad y RBAC
RLS, roles anon/authentiated/service_role: el modelo heredado tal como está por GraphQL.
- CLI
aura proyecta graphql-enable y el resto de comandos del proyecto.