pg_graphql é uma extensão Postgres de código aberto mantida pela Supabase - não é uma invenção da 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 do Hasura e do 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 pelo 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.
- O 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 oficial .deb distribuído pela Supabase. Ele é instalado no cluster compartilhado e nas instâncias dedicadas do Postgres.
Se você vem do Supabase, onde pg_graphql está habilitado nativamente há muito tempo, a lógica lhe será familiar. 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 na Hasura e PostGraphile
Nenhum dos dois concorrentes históricos do “GraphQL instantâneo no 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 do 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 no Postgres, ninguém toca nele” - é o slot específico GraphQL zero-config, ativado em um comando, sem serviço para hospedar. Hasura se afasta disso 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, no Postgres | Servidor GraphQL separado (Go), na frente do Postgres | Biblioteca/servidor Node.js, à frente do Postgres |
|---|---|---|---|
| Implantação necessária | Nenhum — ativado por um sinalizador de projeto | Sim – hospedar e dimensionar o mecanismo Hasura | Sim – hospede o processo Node ou integre-o ao seu servidor |
| Modelo de permissões | RLS Postgres legado (INVOKER DE SEGURANÇA) | Sistema de permissões próprio da 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: o PostGraphile também delega autorização ao Postgres via pgSettings e troca de função - o RLS nativo não é exclusivo do pg_graphql. O que permanece diferente é quem hospeda e configura esta ponte: no PostGraphile, é você; na Aurabase isso já está feito.
Como o Aurabase ativa o 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:
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.
RLS legado, não um segundo sistema para manter
A função definida pelo Aurabase é SECURITY INVOKER — comportamento padrão do Postgres, explicado para que um refator 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 todo o RLS - verificado internamente: chamar graphql.resolve na 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.
No 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 do Hasura. Essas regras são definidas por função e por tabela em sua própria camada — um sistema paralelo ao RLS do Postgres, 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.
A resposta segue a especificação GraphQL — { data, errors } — sem empacotamento adicional do Aurabase: 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 o 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 do Aurabase. O Aurabase em tempo real existe, mas por meio de um canal separado (postgres_changes), não de 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 - no 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 no Aurabase — se seu banco de dados e políticas RLS já residem no Aurabase e você deseja 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 do Aurabase GraphQL, abaixo, também detalha o ciclo completo.