Supabase Postgres Best Practices

ANÁLISE EDITORIAL

Imagem editorial: ilustração exclusiva do Bastidores da IA. Não é captura de tela, interface real nem prova de um banco configurado.

Uma consulta lenta nem sempre precisa de “mais servidor”. Uma política de acesso correta no papel ainda pode expor dados se for aplicada no lugar errado. E uma sugestão de índice, migração ou EXPLAIN ANALYZE pode ser útil em laboratório e perigosa quando chega a produção sem contexto. A Supabase Postgres Best Practices tenta dar ao agente uma biblioteca de regras para raciocinar melhor sobre esses casos antes de escrever ou alterar SQL.

Não é um otimizador automático

A Skill não se conecta sozinha ao Supabase ou ao PostgreSQL, não mede o seu banco e não aplica uma correção. Ela reúne instruções que um agente compatível pode carregar quando trabalha com consultas, índices, conexões, desenho de esquema, concorrência, monitoramento e Row Level Security (RLS). O efeito real depende da pergunta, do contexto fornecido e, principalmente, das ferramentas e permissões concedidas ao agente.

O material organiza as regras em oito frentes com prioridades diferentes. Desempenho de consulta, gerenciamento de conexões e segurança/RLS aparecem como críticos; desenho de esquema vem como alto impacto; bloqueios, acesso a dados, diagnóstico e recursos avançados completam o conjunto. Cada referência costuma apresentar o problema, um exemplo inadequado, uma alternativa e links para documentação.

O pacote que foi aberto e contado

Esta curadoria fixou o commit 1207767388a0ffb55f21fb4e6988fee96942431d do repositório oficial supabase/agent-skills, datado de 30 de julho de 2026. A pasta contém 36 arquivos, todos em Markdown: o manifesto SKILL.md, o changelog e 34 referências. Não há script, binário, dependência empacotada ou credencial.

Há uma diferença de versão que merece ficar visível. O changelog inicia em 1.6.0, mas o campo metadata.version dentro do manifesto ainda informa 1.1.1. Isso não impede a leitura da Skill, porém torna o número isolado uma referência ruim. O download auditável desta página e os links de fonte usam o commit completo para identificar exatamente o material revisado.

Onde a orientação pode ajudar

Os exemplos cobrem situações recorrentes: índice ausente em colunas usadas por filtros e junções; escolha entre pooling por transação ou por sessão; ordem consistente de bloqueios para evitar deadlock; restrições adicionadas de forma idempotente; políticas RLS e privilégios mínimos; além da leitura de planos com EXPLAIN ANALYZE. A proposta é melhorar a qualidade da análise e do SQL sugerido, não prometer um ganho universal.

Esse limite importa porque algumas métricas dos arquivos são exemplos didáticos, não benchmarks executados no seu ambiente. O custo de um índice depende de volume, seletividade e padrão de escrita. O tamanho do pool depende de recursos, proxy e carga. Uma política RLS depende do modelo de identidade e dos testes de isolamento. Copiar um número ou comando sem medir pode trocar um problema por outro.

Permissões ficam fora da Skill, mas o risco não

Instalar os Markdown não concede acesso ao banco. Mesmo assim, a descrição da Skill foi escrita para ativá-la também em mudanças de tabela, migrações, funções, filas, importações e restaurações. Se o agente estiver conectado a uma CLI, MCP ou credencial com escrita, uma solicitação ampla pode chegar a comandos com efeito real.

O próprio pacote contém exemplos de ALTER SYSTEM, criação de índices e políticas, SECURITY DEFINER, privilégios e remoção de partição. EXPLAIN ANALYZE executa a instrução analisada. Por isso, comece com esquema anonimizado, plano já coletado e acesso somente de leitura. Para qualquer mudança, exija SQL em arquivo, revisão de diff, backup, janela de manutenção e rollback testado.

Instalação por projeto e compatibilidade

A documentação da Supabase apresenta o comando npx skills add supabase/agent-skills --skill supabase-postgres-best-practices. O escopo padrão é o projeto, o que facilita versionar e revisar o conteúdo usado pela equipe. A empresa informa compatibilidade do catálogo com mais de 18 agentes; a disponibilidade exata de descoberta automática, ferramentas e permissões varia entre Codex, Claude Code, Cursor, GitHub Copilot e outros clientes.

A Skill declara que as práticas se destinam a PostgreSQL executado em qualquer lugar, embora várias referências tenham observações específicas da Supabase. Isso não transforma uma recomendação de plataforma em regra universal. Compare cada orientação com a versão do PostgreSQL, extensões, serviço gerenciado e política operacional do ambiente real.

Um ensaio que não toca produção

1. Instale a Skill somente em um projeto de teste e registre o commit recebido.
2. Forneça um esquema pequeno e fictício, uma consulta lenta reproduzível e um plano coletado fora da produção.
3. Peça análise e SQL proposto, explicitando que nenhum comando deve ser executado.
4. Confira se a resposta separa hipótese de evidência e cita a regra consultada.
5. Teste o SQL em banco descartável, meça antes e depois e revise segurança, bloqueios e custo de escrita.

Origem, licença e cópia local

O repositório usa licença MIT, preservada no ZIP hospedado pelo Bastidores da IA junto dos 36 Markdown e de um registro de origem. A licença permite redistribuição com manutenção do aviso, mas não oferece garantia. O botão de download local serve para auditoria e reprodutibilidade; o repositório oficial continua sendo a referência separada para atualizações.

Fontes verificadas

• Pasta oficial da Skill no commit auditado
• Licença MIT do repositório
• Documentação oficial de Agent Skills da Supabase
• PostgreSQL, uso de EXPLAIN
• PostgreSQL, políticas de segurança por linha