Supabase

Princípios Fundamentais

1. O Supabase muda com frequência — verifique o changelog e a documentação atual antes de implementar. Não confie nos dados de treinamento para recursos do Supabase. Assinaturas de funções, configurações do config.toml e convenções de API mudam entre versões.

Primeiro, busque https://supabase.com/changelog.md (um índice de resumo leve — não um pull pesado), verifique se há tags breaking-change relevantes para sua tarefa e siga a página vinculada para quaisquer que se apliquem. Em seguida, pesquise o tópico relevante usando os métodos de acesso à documentação abaixo.

2. Verifique seu trabalho. Após implementar qualquer correção, execute uma consulta de teste para confirmar que a alteração funciona. Uma correção sem verificação está incompleta.

3. Recupere-se de erros, não entre em loop. Se uma abordagem falhar após 2-3 tentativas, pare e reconsidere. Tente um método diferente, verifique a documentação, inspecione o erro com mais cuidado e revise os logs relevantes quando disponíveis. Os problemas do Supabase nem sempre são resolvidos repetindo o mesmo comando, e a resposta nem sempre está nos logs, mas os logs geralmente valem a pena verificar antes de prosseguir.

4. Expondo tabelas à API de Dados: Dependendo das configurações da API de Dados do usuário, tabelas recém-criadas podem não ser automaticamente expostas por meio da API de Dados (REST). Se for o caso, as funções anon e authenticated precisarão receber acesso explicitamente.

Observe que isso é separado do RLS, que controla quais linhas são visíveis quando uma tabela está acessível, não se a tabela é acessível.

Quando um usuário relatar que uma tabela criada por SQL está inesperadamente inacessível, verifique as configurações da API de Dados e se as funções receberam acesso através de GRANT SQL explícito. Ao conceder acesso público (anon/authenticated), sempre habilite o RLS também. Consulte Expondo uma Tabela à API de Dados para o fluxo de trabalho completo de configuração.

5. RLS em schemas expostos. Habilite o RLS em todas as tabelas em qualquer schema exposto, o que inclui public por padrão. Isso é crítico no Supabase porque tabelas em schemas expostos podem ser acessadas por meio da API de Dados quando as funções anon/authenticated têm acesso (consulte Expondo uma Tabela à API de Dados). Para schemas privados, prefira RLS como defesa em profundidade. Após habilitar o RLS, crie políticas que correspondam ao modelo de acesso real, em vez de padronizar todas as tabelas para o mesmo padrão auth.uid().

6. Checklist de segurança. Ao trabalhar em qualquer tarefa do Supabase que envolva autenticação, RLS, views, armazenamento ou dados do usuário, execute este checklist. Estas são armadilhas de segurança específicas do Supabase que criam vulnerabilidades silenciosamente:

Segurança de autenticação e sessão
- Nunca use user_metadata em decisões de autorização baseadas em JWT. No Supabase, raw_user_meta_data é editável pelo usuário e pode aparecer em auth.jwt(), portanto, não é seguro para políticas de RLS ou qualquer outra lógica de autorização. Armazene dados de autorização em raw_app_meta_data / app_metadata.
- Excluir um usuário não invalida tokens de acesso existentes. Faça logout ou revogue as sessões primeiro, mantenha a expiração do JWT curta para aplicativos confidenciais e, para garantias estritas, valide session_id em relação a auth.sessions em operações confidenciais.
- Se você usar app_metadata ou auth.jwt() para autorização, lembre-se de que as declarações JWT nem sempre estão atualizadas até que o token do usuário seja atualizado.
Exposição de chave de API e cliente
- Nunca exponha a chave service_role ou secreta em clientes públicos. Prefira chaves publicáveis para código frontend. Chaves anon legadas são apenas para compatibilidade. No Next.js, qualquer variável de ambiente NEXT_PUBLIC_ é enviada ao navegador.
- Use tokens de acesso pessoal com escopo para a API de Gerenciamento, CLI e servidor MCP. Um token de acesso pessoal clássico carrega o acesso total da conta do usuário, em todas as organizações e projetos. Para scripts, CI e agentes, peça ao usuário para criar um token com escopo limitado às organizações, projetos e permissões que a tarefa precisa. O guia de tokens de acesso pessoal lista a permissão que cada endpoint da API de Gerenciamento e ferramenta MCP requer. Consulte as permissões lá em vez de adivinhar.
RLS, Views e código de banco de dados privilegiado
- Views ignoram o RLS por padrão. No Postgres 15 ou superior, use CREATE VIEW ... WITH (security_invoker = true). Em versões mais antigas do Postgres, proteja suas views revogando o acesso das funções anon e authenticated, ou colocando-as em um schema não exposto.
- UPDATE requer uma política SELECT. No RLS do Postgres, um UPDATE precisa primeiro SELECIONAR a linha. Sem uma política SELECT, as atualizações retornam 0 linhas silenciosamente — sem erro, apenas nenhuma alteração.
- auth.role() está obsoleto — use a cláusula TO. O Supabase descontinuou auth.role() em favor da especificação da função alvo diretamente na política com TO authenticated ou TO anon. Além da descontinuação, auth.role() = 'authenticated'' quebra silenciosamente quando logins anônimos estão habilitados, porque os usuários anônimos carregam a função Postgres authenticated e passam na verificação independentemente de o usuário estar realmente logado.
```
-- Obsoleto (não use)
create policy "example" on table_name for select
using ( auth.role() = 'authenticated' );
```
- TO authenticated sozinho é autenticação sem autorização (BOLA / IDOR). Usar TO authenticated apenas verifica a função — ele não restringe quais linhas um usuário pode acessar. O padrão correto combina TO authenticated com um predicado de propriedade em USING:
```
create policy "example" on table_name for select
to authenticated
using ( (select auth.uid()) = user_id );
```
- As políticas UPDATE exigem USING e WITH CHECK. Sem WITH CHECK, um usuário pode reatribuir o user_id de uma linha para outro usuário:
```
create policy "example" on table_name for update
to authenticated
using ( (select auth.uid()) = user_id )
with check ( (select auth.uid()) = user_id );
```
- As funções SECURITY DEFINER ignoram o RLS. Uma função SECURITY DEFINER é executada com os privilégios de seu criador — normalmente uma função com bypassrls (por exemplo, postgres). Nunca adicione SECURITY DEFINER para resolver um erro de permissão; ele remove silenciosamente o controle de acesso sem corrigir a causa subjacente. Prefira SECURITY INVOKER.
- As funções SECURITY DEFINER em public são chamáveis por todas as funções. O Postgres concede EXECUTE a PUBLIC por padrão para cada nova função, portanto, qualquer função SECURITY DEFINER em public é um endpoint de API pública chamável por anon e authenticated (que herdam de PUBLIC) sem qualquer concessão adicional. Quando SECURITY DEFINER é genuinamente necessário (por exemplo, ignorar o RLS em uma tabela de consulta interna), mantenha a função em um schema não exposto, sempre inclua uma verificação auth.uid() no corpo da função e execute supabase db advisors após fazer alterações.
Controle de acesso ao armazenamento
- Upsert do Storage requer INSERT + SELECT + UPDATE. Conceder apenas INSERT permite novos uploads, mas a substituição de arquivos (upsert) falha silenciosamente. Você precisa de todos os três.
Segurança de dependência e cadeia de suprimentos
- Sempre fixe as versões dos pacotes e confirme os lockfiles ao instalar pacotes Supabase (supabase-js, @supabase/ssr, supabase-py, etc.). Consulte o guia de segurança npm para o checklist completo.

Para qualquer preocupação de segurança não coberta acima, busque o índice de segurança do produto Supabase: https://supabase.com/docs/guides/security/product-security.md

CLI do Supabase

Sempre descubra comandos via --help — nunca adivinhe. A estrutura da CLI muda entre versões.

supabase --help                    # Todos os comandos de nível superior
supabase <group> --help            # Subcomandos (ex.: supabase db --help)
supabase <group> <command> --help  # Flags para um comando específico

Armadilhas conhecidas da CLI do Supabase:

supabase db query requer CLI v2.79.0+ → use MCP execute_sql ou psql como fallback
supabase db advisors requer CLI v2.81.3+ → use MCP get_advisors como fallback
O fluxo do navegador de supabase login cria um token clássico com acesso total à conta. Em CI, defina SUPABASE_ACCESS_TOKEN para um token de acesso pessoal com escopo. Ele tem precedência sobre qualquer login salvo. Comandos que se conectam com a senha do banco de dados (--password ou SUPABASE_DB_PASSWORD, por exemplo supabase db push) não são limitados pelas permissões do token.
Em projetos de migração imperativa, crie novos arquivos de migração escritos manualmente com supabase migration new <name> primeiro. Nunca invente um nome de arquivo de migração ou confie na memória para o formato esperado. Projetos de schema declarativo geram migrações de supabase/schemas/; consulte "Fazendo e Confirmando Alterações de Schema" abaixo.

Verificação de versão e atualização: Execute supabase --version para verificar. Para changelogs da CLI e recursos específicos de versão, consulte a documentação da CLI ou os lançamentos do GitHub.

Servidor MCP do Supabase

Para instruções de configuração, URL do servidor e configuração, consulte o guia de configuração do MCP.

Solução de problemas de conexão — siga estas etapas em ordem:

Verifique se o servidor está acessível: curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp Um 401 é esperado (sem token) e significa que o servidor está ativo. Timeout ou "conexão recusada" significa que pode estar inativo.
Verifique a configuração do .mcp.json: Verifique se a raiz do projeto tem um .mcp.json válido com a URL correta do servidor. Se estiver faltando, crie um apontando para https://mcp.supabase.com/mcp.
Autentique o servidor MCP: Se o servidor estiver acessível e .mcp.json estiver correto, mas as ferramentas não estiverem visíveis, o usuário precisa se autenticar. O servidor MCP do Supabase usa OAuth 2.1 — diga ao usuário para acionar o fluxo de autenticação em seu agente, concluí-lo no navegador e recarregar a sessão. Em ambientes CI ou outros onde o fluxo do navegador não pode ser executado, passe um token de acesso pessoal com escopo no cabeçalho Authorization: Bearer.
Verifique as permissões do token com escopo: Se uma ferramenta falhar com "Você não tem permissão para executar esta ação" ao usar um token de acesso pessoal com escopo, o token não tem a permissão dessa ferramenta ou o projeto está fora do escopo do token. Verifique a permissão necessária da ferramenta no guia de tokens de acesso pessoal.

Documentação do Supabase

Antes de implementar qualquer recurso do Supabase, encontre a documentação relevante. Use estes métodos em ordem de prioridade:

Ferramenta MCP search_docs (preferida — retorna trechos relevantes diretamente)
Buscar páginas de documentação como markdown — qualquer página de documentação pode ser buscada anexando .md ao caminho da URL.
Pesquisa na web para tópicos específicos do Supabase quando você não sabe qual página consultar.

Fazendo e Confirmando Alterações de Schema

Primeiro, decida qual fluxo de trabalho de schema o projeto usa.

Opção A: Schemas declarativos

Use esta opção quando supabase/schemas/ existir ou config.toml definir schema_paths. Edite o estado desejado do schema nesses arquivos, em seguida, gere e revise a migração. Não comece escrevendo uma migração manualmente. Consulte o Guia de schemas de banco de dados declarativos.

Opção B: Migrações imperativas

Use esta opção quando o projeto não usar schemas declarativos.

Para fazer alterações de schema, use execute_sql (MCP) ou supabase db query (CLI). Esses comandos executam SQL diretamente no banco de dados sem criar entradas de histórico de migração, para que você possa iterar livremente e gerar uma migração limpa quando estiver pronto.

Não use apply_migration para alterar um schema de banco de dados local — ele escreve uma entrada de histórico de migração em cada chamada, o que significa que você não pode iterar, e supabase db diff / supabase db pull produzirão diffs vazios ou conflitantes. Se você usar, ficará preso ao SQL que passou na primeira tentativa.

Quando estiver pronto para confirmar suas alterações em um arquivo de migração:

Execute os advisors → supabase db advisors (CLI v2.81.3+) ou MCP get_advisors. Corrija quaisquer problemas.
Revise o Checklist de Segurança acima se suas alterações envolverem views, funções, triggers ou armazenamento.
Gere a migração → supabase db pull <nome-descritivo> --local --yes
Verifique → supabase migration list --local

Depuração

Quando você receber um erro em uma solicitação relacionada ao Supabase, por exemplo, um código de erro da API REST do Supabase, banco de dados Postgres ou PostgREST, um resultado vazio, ser bloqueado inesperadamente pelo RLS, ou um erro de um serviço do Supabase como Auth, Realtime, Edge Functions ou Storage, você deve buscar a documentação de Monitoramento e Depuração do Supabase antes de diagnosticar ou propor uma correção, em vez de trabalhar de memória. Os mesmos documentos também cobrem otimizações de desempenho, como consultas lentas e índices ausentes.

Guias de Referência

Feedback da Habilidade → references/skill-feedback.md DEVE ser lido quando o usuário relatar que esta habilidade forneceu orientação incorreta ou está faltando informações.

PhuongDeveloper/landingpage

O que é landingpage?

Perguntar na sua IA favorita

Documentação