Communitygithub.com

Futurists2023/supabase

Use para qualquer tarefa envolvendo Supabase. Aciona: produtos Supabase (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); bibliotecas cliente e integrações SSR (supabase-js, @supabase/ssr) em Next.js, React, SvelteKit, Astro, Remix; problemas de autenticação (login, logout, sessões, JWT, cookies, getSession, getUser, getClaims, RLS); CLI do Supabase ou servidor MCP; alterações de esquema, migrações, esquemas declarativos, auditorias de segurança, extensões Postgres (pg_graphql, pg_cron, pg_vector); depuração e solução de problemas de erros ou comportamento inesperado em projetos Supabase (erros HTTP, erros Postgres, surpresas com RLS, permissão negada, problemas de cache de esquema, timeouts, falhas de Edge Function, quedas de Realtime, falhas de Storage) e leitura ou consulta de logs (Logs Explorer, ClickHouse).

O que é supabase?

Esta skill é um guia abrangente e atualizado para desenvolvedores e agentes de IA que trabalham com a plataforma Supabase. Ela fornece princípios fundamentais de segurança e práticas recomendadas, como a verificação de alterações no changelog, a exposição correta de tabelas à API de Dados, e as armadilhas comuns de segurança relacionadas a autenticação, RLS (Row Level Security), funções SECURITY DEFINER e controle de acesso a Storage. A skill detalha o uso da CLI do Supabase, com comandos essenciais e dicas de solução de problemas, e explica como configurar e autenticar o servidor MCP para acesso programático. Além disso, oferece orientação para fazer e confirmar alterações de esquema, tanto com esquemas declarativos quanto com migrações imperativas, e um processo de depuração estruturado que prioriza a consulta à documentação oficial de monitoramento e depuração do Supabase.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Futurists2023/tiktok/tree/HEAD/.agents/skills/supabase

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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_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, é inseguro 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 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_id contra auth.sessions em operações confidenciais.
    • Se você usa app_metadata ou auth.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.
  • Chave de API e exposição do cliente

    • Nunca exponha a chave service_role ou a chave secreta em clientes públicos. Prefira chaves publicáveis para código front-end. Chaves anon legadas são apenas para compatibilidade. No Next.js, qualquer variável de ambiente NEXT_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.
  • 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ções anon e authenticated, 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áusula TO. O Supabase descontinuou auth.role() em favor da especificação da função de destino 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 usuários anônimos carregam a função Postgres authenticated e 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 authenticated sozinho é autenticação sem autorização (BOLA / IDOR). Usar TO authenticated apenas verifica a função — 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 podem ser chamadas 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, ignorando RLS em uma tabela de pesquisa interna), mantenha a função em um esquema 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 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.

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 query requer CLI v2.79.0+ → use MCP execute_sql ou psql como alternativa
  • supabase db advisors requer CLI v2.81.3+ → use MCP get_advisors como alternativa
  • 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 à 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 de supabase/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:

  1. 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á funcionando. Tempo limite ou "conexão recusada" significa que pode estar inativo.

  2. Verifique a configuração do .mcp.json: Verifique se a raiz do projeto tem um .mcp.json válido com o URL correto do servidor. Se estiver faltando, crie um apontando para https://mcp.supabase.com/mcp.

  3. 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, 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çalho Authorization: Bearer.

  4. 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:

  1. Ferramenta MCP search_docs (preferida — retorna trechos relevantes diretamente)
  2. Busque páginas de documentação como markdown — qualquer página de documentação pode ser buscada anexando .md ao caminho da URL.
  3. 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:

  1. Execute os advisors → supabase db advisors (CLI v2.81.3+) ou MCP get_advisors. Corrija quaisquer problemas.
  2. Revise a Lista de Verificação de Segurança acima se suas alterações envolverem visualizações, funções, gatilhos ou storage.
  3. Gere a migração → supabase db pull <nome-descritivo> --local --yes
  4. 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.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas