Supabase

Quando Usar

Use ao realizar QUALQUER tarefa envolvendo Supabase. Gatilhos: produtos Supabase (Banco de Dados, Autenticação, Funções de Borda, Tempo Real, Armazenamento, Vetores, Cronômetro, Filas); bibliotecas cliente e integrações SSR (supabase-js, @supabase/ssr) em Next.js, React, SvelteKit, Astro, Remix; problemas de autenticação (login, logout,...

Princípios Fundamentais

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

Primeiro, busque https://supabase.com/changelog.md (um índice de resumo leve — não um pull pesado), procure por tags breaking-change relevantes para sua tarefa e siga a página vinculada para quaisquer que se apliquem. Em seguida, procure 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 mudança 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. Problemas do Supabase nem sempre são resolvidos tentando o mesmo comando novamente, 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, novas tabelas podem não ser expostas automaticamente via API de Dados (REST). Se for 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 uma vez que uma tabela é acessível, não se a tabela é acessível ou não.

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

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

6. Checklist de segurança. Ao trabalhar em qualquer tarefa do Supabase que toque em autenticação, RLS, views, armazenamento ou dados do usuário, passe por 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 claims 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 em vez disso.
  • Excluir um usuário não invalida tokens de acesso existentes. Faça logout ou revogue sessões primeiro, mantenha a expiração do JWT curta para aplicativos sensíveis e, para garantias estritas, valide session_id contra auth.sessions em operações sensíveis.
  • Se você usar app_metadata ou auth.jwt() para autorização, lembre-se que as claims 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. Em Next.js, qualquer variável de ambiente NEXT_PUBLIC_ é enviada para o navegador.

• 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 das funções anon e authenticated, ou colocando-as em um esquema não exposto.

…