O PostgREST é um servidor que transforma o schema de um banco PostgreSQL numa API REST. Ele lê as tabelas, as views e as funções expostas e publica rotas HTTP para consultar e gravar registros. A tradução entre a URL e o SQL acontece no próprio servidor.
A proposta reduz o código de uma camada. Em vez de escrever um endpoint para cada tabela, você descreve a estrutura no banco e define as permissões. O PostgREST monta a consulta e devolve JSON.
Uma tabela vira uma rota
Considere uma tabela tarefas no schema public, cuja rota correspondente fica em /tarefas. A consulta abaixo busca as tarefas concluídas, ordenadas pela data:
GET /tarefas?concluida=eq.false&order=criada_em.desc&limit=20Accept: application/jsonO PostgREST traduz os parâmetros para um select com where, order by e limit. Os filtros usam operadores próprios, como eq, gt e like. A resposta traz as linhas em JSON, com o código HTTP correspondente.
A consulta pode incluir relações por embedding. Uma chamada a /faturas?select=numero,clientes(nome) devolve a fatura com o nome do cliente relacionado. A junção é montada a partir das chaves estrangeiras declaradas no banco.
O papel do banco define o acesso
Cada requisição executa com um papel do PostgreSQL. Na configuração mais comum, o token JWT enviado no cabeçalho Authorization contém a identidade e o papel. O PostgREST valida o token e usa esse papel na conexão.
As permissões grant definem quais tabelas e colunas aquele papel pode acessar. As políticas de RLS filtram as linhas. Sem uma política que permita a leitura, a consulta não retorna registros, mesmo que a tabela exista na rota.
Esse desenho coloca a autorização no banco. A API não define sozinha quais registros cada sessão pode ver. A chave publishable identifica o projeto, enquanto o token da sessão define o usuário e o papel.
Funções e lógica no banco
O PostgREST também publica funções. Uma função que recebe parâmetros e devolve uma tabela aparece como uma rota que aceita um POST. Esse caminho serve para uma operação que precisa de várias instruções SQL numa transação.
A lógica no banco tem custo de manutenção, porque fica versionada nas migrations, mas o teste e a leitura exigem acesso ao SQL. Uma operação simples de CRUD costuma ficar melhor na tabela, e uma tarefa que precisa de atomicidade pode virar função.
Cache do schema
O PostgREST mantém um cache da estrutura do banco. Uma tabela criada depois que o servidor iniciou não aparece até o cache ser recarregado. A recarga pode acontecer por um aviso no banco ou por uma chamada administrativa, conforme a configuração.
Quando uma coluna nova não aparece na resposta, a primeira pergunta é se o cache foi atualizado. A segunda é se o papel usado na consulta tem permissão sobre a coluna. As duas causas produzem sintomas parecidos, com respostas diferentes no log.
O que fica fora
O PostgREST não substitui a validação de regra de negócio que depende de vários serviços. Ele também não cria a interface. A aplicação continua responsável por montar a tela, tratar o erro e decidir quando chamar cada rota.
A API gerada é uma superfície pública. A revisão precisa cobrir as rotas expostas, as políticas e os testes com um usuário sem permissão. Um teste que só usa a conta administrativa não mostra o que um visitante consegue ler.
Dúvidas frequentes
Perguntas frequentes sobre PostgREST
- O PostgREST substitui um backend?
- Ele substitui a camada que traduz HTTP em SQL para operações simples. A lógica que não cabe numa consulta ou numa função do banco continua em um serviço próprio, chamado pela aplicação ou por uma função do Postgres.
- As políticas de RLS bastam para proteger a API?
- Não. A RLS precisa estar ativa nas tabelas expostas, e os papéis usados pela API precisam de permissões coerentes. Uma política ausente ou um papel com privilégio amplo deixam a rota acessível.
- Por que uma tabela nova ainda não aparece na API?
- O PostgREST mantém um cache do schema. Depois de criar ou alterar uma tabela, ele precisa recarregar esse cache, por um aviso no banco ou por uma chamada administrativa, conforme a configuração.
Para continuar
Recursos relacionados
Documentação
PostgREST: documentação
Explica a geração da API, os filtros, a paginação, as funções e a configuração do servidor.
Abrir recursoDocumentação
PostgREST: autenticação e autorização
Mostra como o JWT define o papel usado na consulta e como as permissões do Postgres controlam o acesso.
Abrir recursoDocumentação
Supabase: API REST
Apresenta a API gerada pelo PostgREST em um projeto Supabase, com a chave pública, a sessão e as políticas de RLS.
Abrir recursoSite de referência
Promovaweb: banco e API no Supabase
Acompanha o caminho de uma consulta do frontend até as linhas, passando por papéis, grants e políticas.
Abrir recursoAplicação na formação
Vibe Coding: Do Zero ao MVP
Ao criar um projeto no Supabase, você confere as políticas de RLS antes de consumir a API gerada pelo PostgREST no frontend.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.