Ir para o conteúdo
Aura Logo
aurabase

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.

Explicação5 min lidoNível intermediárioRevisado em 11 de nov. de 2026

Esta página foi traduzida automaticamente. A versão em inglês é oficial.

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.

Informações

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 }.

ciclo de uma ativaçãotext
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)
Dica

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 (&lt;table&gt;Collection, edges, node) com colunas SQL snake_case flexionadas para camelCase por 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 com Unknown 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) e inflect_names (created_at → createdAt, ativado por padrão). A receita pg_graphql COMMENT ON SCHEMA … @graphql(...) não funciona em um projeto (sua função não possui o esquema e /raw recusa literais E'…'): use aura projects graphql-config ou PATCH …/graphql/config em vez disso, consulte Ajustar as configurações.
  • Ativação opcional, idempotente. POST .../graphql/enable (console JWT) ou aura 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#

graphql-enable.shbash
# 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
Dica

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).

graphql-config.shbash
# 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.

A introspecção expõe seu esquema

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#

Inflexão de nomenclatura e recargas de esquema

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#