O que Supabase faz?
Princípios Fundamentais
1. A Supabase muda com frequência — verifique o changelog e a documentação atual antes de implementar.
Não confie nos dados de treinamento para funcionalidades da Supabase. Assinaturas de funções, configurações do config.toml e convenções de API mudam entre versões.
Primeiro, acesse https://supabase.com/changelog.md (um índice resumido leve — não uma busca pesada), procure por tags breaking-change relevantes para sua tarefa e siga a página vinculada para qualquer uma que se aplique. Em seguida, consulte 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 repita em loop. Se uma abordagem falhar após 2 a 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 da Supabase nem sempre são resolvidos repetindo o mesmo comando, e a resposta nem sempre está nos logs, mas vale a pena verificar os logs 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 expostas automaticamente pela API REST. Se for esse o caso, será necessário conceder acesso explicitamente aos papéis anon e authenticated.
Observe que isso é separado do RLS, que controla quais linhas são visíveis depois que uma tabela está acessível, e não se a tabela é acessível ou não.
Quando um usuário relatar que uma tabela criada via SQL está inesperadamente inacessível, verifique as configurações da API de Dados e se os papéis receberam acesso via GRANT SQL explícito. Ao conceder acesso público (anon/authenticated), sempre habilite também o RLS. Consulte Expondo uma Tabela à API de Dados para o fluxo de configuração completo.
5. RLS em esquemas expostos.
Habilite o RLS em todas as tabelas de qualquer esquema exposto, o que inclui public por padrão. Isso é crítico na Supabase porque tabelas em esquemas expostos podem ser acessadas pela API de Dados quando os papéis anon/authenticated têm acesso (consulte Expondo uma Tabela à API de Dados). Para esquemas 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 usar o mesmo padrão auth.uid() para todas as tabelas.
6. Lista de verificação de segurança. Ao trabalhar em qualquer tarefa da Supabase que envolva autenticação, RLS, views, armazenamento ou dados do usuário, percorra esta lista. Estas são armadilhas de segurança específicas da Supabase que criam vulnerabilidades silenciosamente:
-
Segurança de autenticação e sessão
- Nunca use claims de
user_metadataem decisões de autorização baseadas em JWT. Na Supabase,raw_user_meta_dataé editável pelo usuário e pode aparecer emauth.jwt(), portanto, não é seguro para políticas de RLS ou qualquer outra lógica de autorização. Armazene dados de autorização emraw_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 sensíveis e, para garantias rigorosas, valide
session_idem relação aauth.sessionsem operações sensíveis. - Se você usar
app_metadataouauth.jwt()para autorização, lembre-se de que as claims do JWT nem sempre estão atualizadas até que o token do usuário seja renovado.
- Nunca use claims de
-
Exposição de chave de API e cliente
- Nunca exponha a chave
service_roleou a chave secreta em clientes públicos. Prefira chaves publicáveis para código frontend. Chavesanonlegadas são apenas para compatibilidade. No Next.js, qualquer variável de ambienteNEXT_PUBLIC_é enviada ao navegador.
- Nunca exponha a chave
-
RLS, views e código de banco de dados privilegiado
- Views ignoram RLS por padrão. No Postgres 15 e superior, use
CREATE VIEW ... WITH (security_invoker = true). Em versões mais antigas do Postgres, proteja suas views revogando o acesso dos papéisanoneauthenticated, ou colocando-as em um esquema não exposto. - UPDATE requer uma política SELECT. No RLS do Postgres, um UPDATE precisa primeiro fazer SELECT da linha. Sem uma política SELECT, updates retornam silenciosamente 0 linhas — sem erro, apenas nenhuma alteração.
auth.role()está obsoleto — use a cláusulaTO. A Supabase descontinuouauth.role()em favor da especificação direta do papel alvo na política comTO authenticatedouTO anon. Além da descontinuação,auth.role() = 'authenticated'quebra silenciosamente quando logins anônimos estão habilitados, porque usuários anônimos carregam o papel Postgresauthenticatede 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 authenticatedsozinho é autenticação sem autorização (BOLA / IDOR). UsarTO authenticatedapenas verifica o papel — não restringe quais linhas um usuário pode acessar. O padrão correto combinaTO authenticatedcom um predicado de propriedade emUSING:create policy "example" on table_name for select to authenticated using ( (select auth.uid()) = user_id );- Políticas de UPDATE exigem
USINGeWITH CHECK. SemWITH CHECK, um usuário pode reatribuir ouser_idde 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 ); - Funções
SECURITY DEFINERignoram RLS. Uma funçãoSECURITY DEFINERé executada com os privilégios de seu criador — normalmente um papel combypassrls(por exemplo,postgres). Nunca adicioneSECURITY DEFINERpara resolver um erro de permissão; ele remove silenciosamente o controle de acesso sem corrigir a causa subjacente. PrefiraSECURITY INVOKER. - Funções
SECURITY DEFINERempublicsão chamáveis por todos os papéis. O Postgres concedeEXECUTEaPUBLICpor padrão para cada nova função, portanto, qualquer funçãoSECURITY DEFINERempublicé um endpoint de API pública chamável poranoneauthenticated(que herdam dePUBLIC) sem qualquer concessão adicional. QuandoSECURITY DEFINERfor realmente necessário (por exemplo, ignorar RLS em uma tabela de consulta interna), mantenha a função em um esquema não exposto, sempre inclua uma verificaçãoauth.uid()no corpo da função e executesupabase db advisorsapós fazer alterações.
- Views ignoram RLS por padrão. No Postgres 15 e superior, use
-
Controle de acesso ao Storage
- Upsert no 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.
Para qualquer preocupação de segurança não coberta acima, acesse o índice de segurança de produtos da Supabase: https://supabase.com/docs/guides/security/product-security.md
CLI da Supabase
Sempre descubra comandos usando --help — nunca adivinhe. A estrutura da CLI muda entre versões.
supabase --help # Todos os comandos de nível superior
supabase <grupo> --help # Subcomandos (ex.: supabase db --help)
supabase <grupo> <comando> --help # Flags para um comando específico
Pegadinhas conhecidas da CLI da Supabase:
supabase db queryrequer CLI v2.79.0+ → use MCPexecute_sqloupsqlcomo alternativasupabase db advisorsrequer CLI v2.81.3+ → use MCPget_advisorscomo alternativa- Quando você precisar de um novo arquivo SQL de migração, sempre crie-o primeiro com
supabase migration new <nome>. Nunca invente um nome de arquivo de migração ou confie na memória para o formato esperado.
Verificação de versão e atualização: Execute supabase --version para verificar. Para changelogs da CLI e funcionalidades específicas de versão, consulte a documentação da CLI ou os lançamentos no GitHub.
Servidor MCP da Supabase
Para instruções de configuração, URL do servidor e configuração, consulte o guia de configuração 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/mcpUm401é esperado (sem token) e significa que o servidor está ativo. Timeout ou "connection refused" significa que pode estar inativo. -
Verifique a configuração do
.mcp.json: Verifique se a raiz do projeto tem um.mcp.jsonválido com a URL correta do servidor. Se estiver faltando, crie um apontando parahttps://mcp.supabase.com/mcp. -
Autentique o servidor MCP: Se o servidor estiver acessível e o
.mcp.jsonestiver correto, mas as ferramentas não estiverem visíveis, o usuário precisa se autenticar. O servidor MCP da Supabase usa OAuth 2.1 — informe ao usuário para acionar o fluxo de autenticação em seu agente, concluí-lo no navegador e recarregar a sessão.
Documentação da Supabase
Antes de implementar qualquer funcionalidade da 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 obtida anexando
.mdao caminho da URL. - Pesquisa na web para tópicos específicos da Supabase quando você não souber qual página consultar.
Fazendo e Confirmando Alterações no Esquema
Para fazer alterações no esquema, use execute_sql (MCP) ou supabase db query (CLI). Eles executam SQL diretamente no banco de dados sem criar entradas no histórico de migração, permitindo iterar livremente e gerar uma migração limpa quando estiver pronto.
NÃO use apply_migration para alterar um esquema de banco de dados local — ele escreve uma entrada no histórico de migração a 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ê usá-lo, 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 MCPget_advisors. Corrija quaisquer problemas. - Revise a Lista de Verificação de Segurança acima se suas alterações envolverem views, funções, triggers ou storage.
- Gere a migração →
supabase db pull <nome-descritivo> --local --yes - Verifique →
supabase migration list --local
Guias de Referência
- Feedback sobre o Skill → references/skill-feedback.md DEVE ler quando o usuário relatar que este skill forneceu orientação incorreta ou está faltando informações.