GráficoQL
Postgres extensão pg_graphql, opcional por projeto e desativado por padrão. Uma vez ativado, ele expõe o mesmo esquema da sua API REST — herdando RLS e funções sem autenticação GraphQL separada — por meio de rotas /graphql dedicadas ou do proxy RPC genérico.
Uma segunda maneira de consultar o mesmo esquema, não um serviço separado#
GraphQL é alimentado diretamente pela extensão Postgres pg_graphql dentro de seu banco de dados de locatário, gerando um esquema GraphQL a partir de suas tabelas SQL, visualizações e relacionamentos. Ativá-lo adiciona uma segunda superfície de consulta sobre o mesmo esquema Postgres que sua API REST – herdando exatamente as mesmas políticas e funções RLS, sem um servidor GraphQL separado ou camada de autenticação.
Desativado por padrão para todos os projetos. Aurabase ativa pg_graphql apenas na aceitação explícita por projeto. Consulte a documentação oficial pg_graphql para consulta completa, filtro, paginação do cursor e sintaxe de mutação.
Um resolvedor SQL exposto em /graphql e /rpc/graphql#
Habilitar GraphQL em um projeto instala pg_graphql e cria "<project_schema>".graphql(query, variables, operationName, extensions) em uma única transação. Em um subdomínio de projeto, as solicitações para POST /graphql, POST /graphql/v1, POST /v1/graphql, POST /v1/graphql/v1 e POST /v1/db/{project_id}/graphql (assim como POST /v1/db/{project_id}/rpc/graphql) são roteadas para pg_graphql e retornam a carga JSON padrão { "data": ..., "errors": ... } GraphQL JSON diretamente sem o wrapper REST { data, meta }.
ACTIVATION ────▶ POST .../graphql/enable ou projetos aura graphql-enable
ENQUEUE ────▶ trabalho "graphql_enable" na fila (idempotente, não operacional se já estiver ativado)
DDL ────▶ CREATE EXTENSION pg_graphql + função wrapper + GRANTs, 1 única transação
FLAG ────▶ projetos.graphql_enabled = true, definido somente após confirmação completa da transação
QUERY ────▶ POST /graphql ou /v1/db/{project_id}/graphql (retorna JSON GraphQL bruto)
A transação de ativação é atômica: se alguma etapa (extensão, função wrapper ou GRANTs) falhar, tudo será revertido e graphql_enabled permanecerá false.
O que a ativação configura#
- Esquema gerado automaticamente. pg_graphql introspecta seu esquema Postgres e expõe cada tabela como um tipo Relay GraphQL (
<table>Collection,edges,node) com colunas SQLsnake_caseflexionadas paracamelCasepor padrão - sem SDL para escrever manualmente. - INVOCADOR DE SEGURANÇA — Herdado RLS. A função wrapper é executada com os privilégios do chamador (
aura_anon/aura_authenticated/aura_service_role), aplicando exatamente as mesmas políticas RLS que as solicitações REST. - Três configurações que você pode alterar, aplicadas atomicamente.
introspection(desativado por padrão:{ __schema { ... } }é recusado comUnknown field "__schema", então GraphiQL e Apollo codegen não podem descobrir o esquema até que você o ative),max_rows(linhas retornadas por coleção, 1 a 10000, padrão 1000) einflect_names(created_at→createdAt, ativado por padrão). A receita pg_graphqlCOMMENT ON SCHEMA … @graphql(...)não funciona em um projeto (sua função não possui o esquema e/rawrecusa literaisE'…'): useaura projects graphql-configouPATCH …/graphql/configem vez disso, consulte Ajustar as configurações. - Ativação opcional, idempotente.
POST .../graphql/enable(console JWT) ouaura projects graphql-enable --wait(CLI) despacha o trabalho de provisionamento e, com--wait, retorna quando o GraphQL está realmente habilitado; nunca ligado automaticamente. - Disponível em todas as camadas Postgres. Funciona se o seu projeto for executado em um cluster Postgres da organização ou em um cluster corporativo dedicado; validado ponta a ponta (extensão, wrapper RLS, consulta real).
- Postgres somente projetos. Um projeto MongoDB recusa a ativação (
GRAPHQL_UNSUPPORTED_ENGINE).
Ative e depois consulte#
# Idempotente: uma chamada repetida em um projeto já habilitado é autônoma.
# --wait retorna quando o GraphQL está realmente habilitado (a ativação é um trabalho em segundo plano).
aura projects graphql-enable <project_id> --wait
A ativação responde com o projeto atualizado (graphql_enabled: true). Observe a inflexão da coluna (created_at → createdAt): consulte a referência oficial da API pg_graphql para filtros, orderBy, paginação do cursor (first/after) e mutações (insertInto<Table>Collection).
Ajuste as configurações: introspecção, máximo de linhas, inflexão de nome#
pg_graphql lê suas configurações de um comentário no esquema do seu projeto. Somente o proprietário do esquema pode escrevê-lo, então a plataforma faz isso para você, em uma transação, quando você solicitar. Uma mudança é idempotente (pedir o que já está aplicado não faz nada) e limitada (max_rows fora de 1–10000 é recusado antes que qualquer coisa seja colocada na fila).
# Mostrar as configurações em vigor
aura projects graphql-config <project_id>
# Ative a introspecção (GraphiQL, graphql-codegen, Apollo), espere até que ela seja aplicada
aura projects graphql-config <project_id> --introspection on --wait
# Limite as coleções em 100 linhas e mantenha os nomes SQL como estão
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait
state diz a verdade sobre a mudança: pending enquanto ela está sendo aplicada (com pending_config), failed se não puder ser (as configurações em config ainda são as que estão em vigor), applied caso contrário. GraphQL deve ser habilitado primeiro (GRAPHQL_NOT_ENABLED caso contrário) e uma segunda alteração enquanto houver respostas pendentes GRAPHQL_CONFIG_PENDING: tente novamente em alguns segundos.
Com introspection ativado, qualquer pessoa que possua a chave pública do projeto pode listar todas as tabelas e colunas expostas pelo GraphQL (RLS ainda protege as linhas). Ative-o para desenvolvimento e desligue-o novamente para produção se o formato do seu esquema for sensível.
Pontos de atenção#
Por padrão, pg_graphql flexiona nomes SQL snake_case para GraphQL camelCase (created_at se torna createdAt, a tabela blog_posts se torna blogPostsCollection). Após as alterações de DDL, PostgREST recarrega seu cache de esquema em segundos para que /graphql e /rpc/graphql exponham os campos atualizados.
Para ir mais longe#
- Banco de dados
Postgres gerenciado, extensões habilitadas, RLS — o esquema que pg_graphql expõe.
- Chame uma função Postgres
O proxy RPC genérico (/rpc/{function}) usado por consultas GraphQL.
- Segurança e RBAC
RLS, funções anon/authenticated/service_role — o modelo herdado como está pelo GraphQL.
- CLI
aura projeta graphql-enable e o restante dos comandos do projeto.