O que supabase faz?
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 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. 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 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 serem verificados 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 via API de Dados (REST). Se for esse o caso, as funções anon e authenticated precisarão ter acesso explicitamente concedido.
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 via SQL está inesperadamente inacessível, verifique as configurações da API de Dados e se as funções receberam acesso via 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 esquemas expostos.
Habilite o RLS em todas as tabelas em qualquer esquema exposto, que inclui public por padrão. Isso é crítico no Supabase porque as tabelas em esquemas expostos podem ser alcançadas através da API de Dados quando as funções 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 padronizar todas as tabelas para o mesmo padrão auth.uid().
6. Lista de verificação de segurança. Ao trabalhar em qualquer tarefa do Supabase que envolva autenticação, RLS, visualizações, armazenamento ou dados do usuário, percorra esta lista de verificação. Estas são armadilhas de segurança específicas do Supabase que criam silenciosamente vulnerabilidades:
-
Segurança de autenticação e sessão
- Nunca use declarações
user_metadataem decisões de autorização baseadas em JWT. No Supabase,raw_user_meta_dataé editável pelo usuário e pode aparecer emauth.jwt(), portanto, é inseguro 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 os tokens de acesso existentes. Saia ou revogue as sessões primeiro, mantenha a expiração do JWT curta para aplicativos confidenciais e, para garantias estritas, valide
session_idcontraauth.sessionsem operações confidenciais. - Se você usa
app_metadataouauth.jwt()para autorização, lembre-se de que as declarações JWT nem sempre são atuais até que o token do usuário seja atualizado.
- Nunca use declarações
-
Chave de API e exposição do cliente
- Nunca exponha a chave
service_roleou a chave secreta em clientes públicos. Prefira chaves publicáveis para código front-end. Chavesanonlegadas são apenas para compatibilidade. No Next.js, qualquer variável de ambienteNEXT_PUBLIC_é enviada para o navegador. - Use tokens de acesso pessoais 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 pessoais lista a permissão que cada endpoint da API de Gerenciamento e ferramenta MCP exige. Consulte as permissões lá em vez de adivinhar.
- Nunca exponha a chave
-
RLS, visualizações e código de banco de dados privilegiado
- As visualizações ignoram o 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 visualizações revogando o acesso das funçõesanoneauthenticated, ou colocando-as em um esquema não exposto. - UPDATE requer uma política SELECT. No RLS do Postgres, um UPDATE precisa primeiro SELECTionar a linha. Sem uma política SELECT, as atualizações retornam silenciosamente 0 linhas — nenhum erro, apenas nenhuma alteração.
auth.role()está obsoleto — use a cláusulaTO. O Supabase descontinuouauth.role()em favor da especificação da função de destino diretamente 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 a função Postgresauthenticatede passam na verificação, independentemente de o usuário estar realmente conectado.-- Descontinuado (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 a função — 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 );- As políticas 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 ); - As funções
SECURITY DEFINERignoram o RLS. Uma funçãoSECURITY DEFINERé executada com os privilégios de seu criador — normalmente uma função 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. - As funções
SECURITY DEFINERempublicpodem ser chamadas por todas as funções. 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 DEFINERé genuinamente necessário (por exemplo, ignorando RLS em uma tabela de pesquisa 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.
- As visualizações ignoram o 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 arquivo (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 confira os lockfiles ao instalar pacotes Supabase (
supabase-js,@supabase/ssr,supabase-py, etc.). Consulte o guia de segurança npm para a lista de verificação completa.
- Sempre fixe as versões dos pacotes e confira os lockfiles ao instalar pacotes Supabase (
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 <grupo> --help # Subcomandos (ex: supabase db --help)
supabase <grupo> <comando> --help # Flags para um comando específico
Pegadinhas conhecidas da CLI do Supabase:
supabase db queryrequer CLI v2.79.0+ → use MCPexecute_sqloupsqlcomo alternativasupabase db advisorsrequer CLI v2.81.3+ → use MCPget_advisorscomo alternativa- O fluxo do navegador de
supabase logincria um token clássico com acesso total à conta. Em CI, definaSUPABASE_ACCESS_TOKENpara 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 (--passwordouSUPABASE_DB_PASSWORD, por exemplosupabase 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 à mão com
supabase migration new <nome>primeiro. Nunca invente um nome de arquivo de migração ou confie na memória para o formato esperado. Projetos de esquema declarativo geram migrações a partir desupabase/schemas/; consulte "Fazendo e Confirmando Alterações de Esquema" abaixo.
Verificação de versão e atualização: Execute supabase --version para verificar. Para changelogs da CLI e recursos específicos da 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 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á funcionando. Tempo limite 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.jsonválido com o URL correto do servidor. Se estiver faltando, crie um apontando parahttps://mcp.supabase.com/mcp. -
Autentique o servidor MCP: Se o servidor estiver acessível e
.mcp.jsonestiver 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, completá-lo no navegador e recarregar a sessão. Em CI ou outros ambientes onde o fluxo do navegador não pode ser executado, passe um token de acesso pessoal com escopo no cabeçalhoAuthorization: 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 pessoais.
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) - Busque páginas de documentação como markdown — qualquer página de documentação pode ser buscada anexando
.mdao 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 Esquema
Primeiro, decida qual fluxo de trabalho de esquema o projeto usa.
Opção A: Esquemas declarativos
Use esta opção quando supabase/schemas/ existir ou config.toml definir schema_paths. Edite o estado desejado do esquema nesses arquivos, em seguida, gere e revise a migração. Não comece escrevendo uma migração manualmente. Consulte o Guia de esquemas de banco de dados declarativos.
Opção B: Migrações imperativas
Use esta opção quando o projeto não usa esquemas declarativos.
Para fazer alterações de esquema, use execute_sql (MCP) ou supabase db query (CLI). Estes 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 esquema 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 MCPget_advisors. Corrija quaisquer problemas. - Revise a Lista de Verificação de Segurança acima se suas alterações envolverem visualizações, funções, gatilhos ou storage.
- Gere a migração →
supabase db pull <nome-descritivo> --local --yes - Verifique →
supabase migration list --local
Depuração
Ao 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. A mesma documentação também cobre otimizações de desempenho, como consultas lentas e índices ausentes.
Guias de Referência
- Feedback da Skill → references/skill-feedback.md DEVE ser lido quando o usuário relatar que esta skill deu orientação incorreta ou está faltando informações.