pg_graphql é uma extensão Postgres de código aberto mantida por Supabase – não é uma invenção Aurabase. O que construímos é a sua integração nativa e opcional na plataforma: uma caixa para marcar por projeto, não um serviço para fornecer. Esta postagem detalha a arquitetura real, mostra como ativá-la e compara honestamente as vantagens e desvantagens com Hasura e PostGraphile v5.
pg_graphqlexecuta em Postgres como uma extensão SQL — nenhum servidor GraphQL separado para implantar, ao contrário de Hasura e PostGraphile.- A função wrapper fornecida por Aurabase é
SECURITY INVOKER: suas políticas RLS se aplicam automaticamente, sem um segundo sistema de permissão para manter em paralelo. - Ativação opcional apenas por projeto —
aura projects graphql-enableou Studio — nunca ativada por padrão, em nenhum projeto. - Hasura reorientou oficialmente seu foco em PromptQL e agentes de IA em junho de 2025, sem abandonar seu mecanismo GraphQL.
- PostGraphile v5 foi disponibilizado ao público em 24 de março de 2026 – um concorrente direto e ativo, não um projeto inativo.
pg_graphql, em uma frase
pg_graphql introspecta seu esquema SQL e gera um esquema GraphQL em conformidade com a convenção Relay - <table>Collection, edges, node, filtros por tipo de coluna, paginação por cursor. Nenhum SDL para escrever ou manter manualmente: o esquema GraphQL segue seu esquema Postgres.
O ponto que importa para a arquitetura: esse gerador de esquema reside dentro do banco de dados, como uma função SQL, não como um processo HTTP próximo a ele. Aurabase fixa a versão 1.6.1 da extensão (lançada em 7 de maio de 2026) em sua imagem Postgres — o mesmo pacote .deb oficial distribuído por Supabase. Ele é instalado no cluster compartilhado e nas instâncias Postgres dedicadas.
Se você vem de Supabase, onde pg_graphql está habilitado nativamente há muito tempo, a lógica será familiar para você. Nossa comparação detalhada de e nosso guia de migração cobrem o restante do esquema e das políticas RLS, que permanecem os mesmos.
O que mudou em Hasura e PostGraphile
Nenhum dos dois concorrentes históricos do “instant GraphQL on Postgres” desapareceu. O seu posicionamento mudou, e um artigo actualizado deveria reflectir isso em vez de citar o estado de há dois anos.
Hasura publicou uma postagem em junho de 2025 com o título explícito, “From GraphQL to PromptQL: A New Chapter Begins”, assinado por seu cofundador Tanmai Gopal. A mensagem: a empresa está redirecionando seu roteiro em PromptQL, uma camada de acesso a dados projetada para agentes de IA. O mecanismo GraphQL não foi removido - a página inicial de Hasura ainda o apresenta como "testado em batalha" - mas não é mais a mensagem prioritária.
PostGraphile, por sua vez, fez o oposto. Sua versão 5, em desenvolvimento desde 2023 na forma de betas, tornou-se disponível em 24 de março de 2026, com um novo mecanismo de planejamento de consultas chamado Grafast. Este não é um projeto que está perdendo força: a última versão, 5.1.4, data de 5 de agosto de 2026. O pacote npm contou 119.230 downloads somente na semana de 16 a 22 de agosto de 2026 (registro npm, consultado em 23 de agosto de 2026).
Consequência prática: o verdadeiro espaço vago não é “GraphQL em Postgres, ninguém toca nele” - é o slot GraphQL zero-config específico, ativado em um comando, sem serviço para hospedar. Hasura se afasta dela por escolha estratégica; PostGraphile nunca teve como alvo, seu modelo continua sendo “biblioteca Node.js para integração”.
Onde cada solução realmente gira
A diferença que estrutura todo o resto – custo operacional, superfície de ataque, latência – é onde o mecanismo GraphQL é executado.
| Onde isso vira | Extensão SQL, em Postgres | Servidor GraphQL separado (Go), na frente de Postgres | Biblioteca/servidor Node.js, à frente de Postgres |
|---|---|---|---|
| Implantação necessária | Nenhum — ativado por um sinalizador de projeto | Sim — hospede e dimensione o mecanismo Hasura | Sim – hospede o processo Node ou integre-o ao seu servidor |
| Modelo de permissões | Postgres RLS herdado (INVOKER DE SEGURANÇA) | Sistema de permissões próprio de Hasura, por função/tabela | RLS Postgres via pgSettings — delegação nativa também |
| Introspecção por padrão | Desativado | Dependendo da configuração do motor | Dependendo da configuração do servidor |
| Posicionamento 2026 | Opção nativa de um Postgres BaaS | Focado novamente em PromptQL/IA desde junho de 2025 | GA v5 desde março de 2026, projeto ativo |
| AURABASE | HASURA | PÓS-GRÁFICO V5 |
Para ser honesto: PostGraphile também delega autorização para Postgres via pgSettings e troca de função - RLS nativo não é exclusivo de pg_graphql. O que permanece diferente é quem hospeda e configura esta ponte: em PostGraphile, é você; em Aurabase, isso já está feito.
Como Aurabase ativa pg_graphql em um projeto
A ativação é opcional, por projeto, e reservada para projetos de mecanismo Postgres - um projeto MongoDB recusa a solicitação (GRAPHQL_UNSUPPORTED_ENGINE), sendo pg_graphql uma extensão Postgres sem equivalente no outro mecanismo.
Através da CLI ou chamando diretamente o plano de manejo:
# Idempotente: recuperar um projeto já ativado não recria nada
aura projects graphql-enable <project_id>
# Equivalente HTTP (plano de gerenciamento, console JWT)
curl -X POST "$AURA_CONTROL_URL/v1/control/projects/$PROJECT_ID/graphql/enable" \
-H "Authorization: Bearer $CONSOLE_JWT"
No lado do servidor, a chamada executa um trabalho graphql_enable que o provisionador executa em uma única transação: instalação da extensão, criação da função graphql() em seu esquema, GRANTs para as funções da aplicação. Se uma etapa falhar, tudo será cancelado - nunca um wrapper é instalado no meio do caminho e graphql_enabled só passa para true após sucesso completo.
Ele funciona tanto no cluster Postgres compartilhado quanto em uma instância CNPG dedicada por projeto – duas imagens Postgres diferentes, mas o mesmo mecanismo de extensão. Em instâncias dedicadas, a extensão é instalada por meio do manifesto declarativo do operador CNPG em vez de SQL direto — uma correção recente. Um cluster dedicado é executado sem acesso de superusuário do aplicativo e pg_graphql requer exatamente esse privilégio para seu CREATE EXTENSION.
No Studio, o mesmo fluxo passa pela aba Configuração da Tabela. Um botão ali ativa a extensão no nível do projeto — a mesma chamada HTTP acima, com polling até a convergência. Um segundo controle então define uma diretiva @graphql por tabela, para ativar ou não totalCount e os campos de agregação em sua coleção GraphQL, sem sair do editor.
Visualização de comando único: ativação → tarefa de provisionamento encadeada (idempotente, sem operação se já estiver em andamento) → transação DDL (extensão, função wrapper, GRANTs) → sinalizador graphql_enabled definido somente após sucesso completo → solicitações possíveis via /rpc/graphql.
Legacy RLS, não é um segundo sistema para manter
A função definida por Aurabase é SECURITY INVOKER — comportamento padrão de Postgres, explicado para que um refatorador futuro não o altere por acidente. Ele é executado com os privilégios do chamador real (aura_anon, aura_authenticated ou aura_service_role, dependendo da declaração JWT), portanto, suas políticas RLS se aplicam exatamente como para uma solicitação REST.
Uma função SECURITY DEFINER ignoraria RLS inteiro - verificado internamente: chamar graphql.resolve sob conexão de superusuário sem alterar a função do aplicativo retorna as linhas de todos os proprietários, RLS ou não. Exatamente o risco entre inquilinos que esta escolha evita.
Em Hasura, a arquitetura é diferente por construção: o mecanismo converte cada consulta GraphQL em uma consulta SQL restrita por regras de permissão específicas para Hasura. Essas regras são definidas por função e por tabela em sua própria camada — um sistema paralelo ao Postgres RLS, não uma delegação a ele. Dois locais para auditar regras de acesso, em vez de apenas um.
A introspecção ({ __schema { ... } }) permanece desabilitada por padrão em cada projeto Aurabase — uma postura consistente com o resto da plataforma. Ele pode ser ativado por esquema via COMMENT ON SCHEMA se uma ferramenta como Apollo Studio ou graphql-codegen precisar.
Habilite e consulte sua API GraphQL
Depois de graphql_enabled para true, nenhuma rota /graphql dedicada aparece no gateway. A solicitação passa pelo proxy RPC genérico, assim como qualquer função Postgres chamada do SDK.
curl -X POST "$NEXT_PUBLIC_AURABASE_URL/v1/db/$PROJECT_ID/rpc/graphql" \
-H "apikey: $NEXT_PUBLIC_AURABASE_ANON_KEY" -H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-d '{"query":"query { postsCollection(first: 10, filter: { published: { eq: true } }) { edges { node { id title created_at } } } }"}'
A resposta segue a especificação GraphQL — { data, errors } — sem empacotamento Aurabase adicional: o gateway detecta que o RPC de destino é graphql e não o reembrulha, ao contrário de um RPC comum. Um cliente GraphQL padrão (Apollo, urql, graphql-request) consome a saída como está.
Duas configurações são definidas por padrão na ativação, por meio de uma diretiva @graphql no diagrama: max_rows: 1000 e inflect_names: true. pg_graphql limita por padrão a 10.000 linhas por coleção — sem first:, uma tabela grande pode saturar a memória. inflect_names fornece nomes de tipos legíveis em vez do Snake_case bruto das tabelas SQL.
O que pg_graphql não faz (ainda)
Para ser documentado em vez de oculto, no espírito deste blog.
- Nenhuma assinatura nativa do GraphQL. pg_graphql cobre consultas e mutações, não
subscriptionsem tempo real — esta é uma limitação da extensão em si, não uma omissão de Aurabase. Aurabase em tempo real existe, mas por meio de um canal separado (postgres_changes), não uma ponte de assinaturas GraphQL. - Nenhuma ação declarativa à la Hasura. O modelo “webhook de negócios conectado a uma mutação GraphQL” não tem equivalente direto - em Aurabase, essa lógica passa por uma função Postgres ou Edge Function, não por uma configuração GraphQL dedicada.
- Reservado para o mecanismo Postgres. Um projeto MongoDB não pode permitir isso – nenhuma solução alternativa pretendida.
Por que a ativação permanece opcional em vez de padrão: A área GRANT/Roles do banco de dados de locatários tem um histórico documentado de regressões. Isto é suficiente para justificar que nenhuma funcionalidade o atinge sem validação explícita, projeto por projeto, antes de considerar um defeito mais amplo.
Aurabase, Hasura ou PostGraphile: dependendo do seu contexto
Todas as três opções são legítimas – a escolha certa depende do que você já tem e do que deseja evitar.
- pg_graphql em Aurabase — se seu banco de dados e políticas RLS já estiverem ativos em Aurabase e você quiser uma segunda maneira de consultá-lo sem serviços adicionais para monitorar.
- Hasura — se você federar várias fontes de dados (não apenas Postgres) por trás de um único esquema GraphQL ou se o PromptQL e sua abordagem de agente de IA se adequarem ao seu roteiro.
- PostGraphile v5 — se você deseja um controle preciso sobre o esquema gerado por meio de seu sistema de plug-ins e já executa um servidor Node.js no qual integrá-lo.
Para sintaxe de consulta completa - filtros por tipo de coluna, classificação orderBy, paginação por cursor, mutações insertInto<Table>Collection - consulte a documentação oficial pg_graphql. A documentação Aurabase GraphQL, abaixo, também detalha o ciclo completo.