supabase-postgres-best-practices

Visão geral da skill supabase-postgres-best-practices

A skill supabase-postgres-best-practices é uma referência estruturada de otimização de Postgres criada pela Supabase para quem precisa tomar decisões melhores sobre SQL, schema, indexação, RLS e gerenciamento de conexões do que um prompt genérico de programação costuma entregar. Ela é mais indicada para engenheiros de banco de dados, desenvolvedores backend e revisores assistidos por IA que trabalham com Supabase ou com ambientes Postgres puros em que desempenho e correção importam ao mesmo tempo.

O que essa skill realmente ajuda você a fazer

Use supabase-postgres-best-practices quando seu trabalho real não for “explicar Postgres”, mas sim coisas como:

• reescrever uma query lenta
• escolher o formato de índice correto
• evitar N+1 e padrões ruins de paginação
• melhorar a segurança de RLS sem destruir a performance
• reduzir contenção de locks
• diagnosticar se o gargalo está na query, no schema ou no padrão de conexão

O valor aqui é que a skill é organizada em arquivos de regras práticos, com exemplos de SQL ruim versus SQL bom, em vez de apenas conselhos genéricos.

Melhores perfis de uso e tipos de projeto

Esta skill atende melhor equipes que:

• operam apps baseados em Supabase e querem orientação específica de Postgres
• revisam migrations, funções SQL, policies ou mudanças de schema com ajuda de IA
• querem padrões repetíveis de otimização para trabalho de Database Engineering
• precisam de exemplos concretos sobre indexação, connection pooling, monitoramento e planos de execução

Ela é especialmente útil se você já tem contexto do schema ou das queries e quer que o modelo proponha melhorias fundamentadas, em vez de cair no conselho genérico de “adicionar índices”.

Por que essa skill é melhor do que um prompt comum

O principal diferencial está na cobertura e na priorização. O repositório agrupa as orientações em oito categorias, começando pelas áreas mais críticas: performance de queries, gerenciamento de conexões e segurança/RLS. Os arquivos de apoio em references/ também mostram transformações exatas, impacto quantificado e tradeoffs, o que dá ao modelo material muito mais forte para aplicar do que uma instrução solta como “otimize meu Postgres”.

O que ela cobre bem

A supabase-postgres-best-practices skill se destaca principalmente em:

• estratégia de indexação de queries, incluindo índices compostos, covering, parciais e ausentes
• decisões de schema como tipos de dados, chaves primárias, constraints, particionamento e indexação de foreign keys
• tópicos operacionais como limites de conexão, pooling, prepared statements e idle timeouts
• padrões de concorrência como advisory locks, transações curtas, prevenção de deadlocks e SKIP LOCKED
• monitoramento com EXPLAIN ANALYZE, pg_stat_statements e vacuum/analyze
• recursos avançados do Postgres, como indexação de JSONB e busca full-text

Onde ela não é a ferramenta certa

Isto não é um manual completo de administração de Postgres, nem um framework de migração, nem uma suíte de benchmark. Se você precisa de tuning específico de ambiente no nível de dimensionamento de hardware, configuração de WAL ou arquitetura profunda de replicação, esta skill funciona mais como um guia prático de queries e schema do que como um playbook completo de DBA.

Como usar a skill supabase-postgres-best-practices

Como instalar supabase-postgres-best-practices

Se o seu executor de skills oferece suporte a instalação remota via GitHub, use:

npx skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practices

Se o seu ambiente carrega skills a partir de um repositório clonado, a skill está em:

skills/supabase-postgres-best-practices

Como SKILL.md não traz um comando de instalação próprio, quem usa a skill pelo diretório deve seguir o fluxo de instalação no nível do repositório acima ou as convenções locais do seu carregador de skills.

Leia estes arquivos primeiro

Para chegar ao uso produtivo mais rápido, leia nesta ordem:

1. skills/supabase-postgres-best-practices/SKILL.md
2. skills/supabase-postgres-best-practices/AGENTS.md
3. skills/supabase-postgres-best-practices/references/_sections.md
4. os arquivos específicos em references/*.md que correspondem ao seu problema

O README.md é mais voltado a contribuidores. Ele é útil se você quiser estender ou validar a skill, mas é menos importante no primeiro uso.

Comece pela categoria, não pelo repositório inteiro

A skill fica bem mais fácil de usar se você primeiro mapear seu problema para um dos prefixos do repositório:

• query- para SQL lento e índices
• conn- para problemas de conexão em ambientes serverless ou de alta concorrência
• security- para privilégios e RLS
• schema- para design de tabelas e colunas
• lock- para contenção e workers de fila
• data- para batching, paginação, upsert e N+1
• monitor- para diagnóstico
• advanced- para JSONB e busca full-text

Isso reduz desvio de prompt e coloca o modelo mais rápido na família certa de solução.

Que entradas geram bons resultados

A qualidade de uso de supabase-postgres-best-practices depende fortemente do nível de especificidade da sua entrada. Forneça ao modelo:

• a query SQL atual ou a migration
• definições relevantes de tabelas
• contagem de linhas ou escala estimada
• índices atuais
• sintomas de lentidão, como latência, CPU, locks ou esgotamento de conexões
• se você está usando recursos do Supabase, como RLS ou conexões com pooling
• quaisquer restrições de correção, como “must preserve cursor order” ou “policy must remain tenant-safe”

Sem isso, você normalmente vai receber sugestões amplamente corretas, mas rasas.

Transforme um objetivo vago em um prompt forte

Prompt fraco:

Optimize this Postgres query.

Prompt melhor:

Use the supabase-postgres-best-practices skill to review this query for index use, data access pattern issues, and RLS impact. Explain likely bottlenecks, propose rewritten SQL, recommend exact indexes, and note tradeoffs. Context: table sizes, existing indexes, and EXPLAIN ANALYZE are below.

Melhor estrutura de prompt:

• objetivo
• SQL/schema/policy atual
• formato da carga de trabalho
• restrições
• formato de saída desejado

Essa estrutura combina bem com a forma como os arquivos de referência ensinam as transformações.

Exemplo de prompt para otimização de queries

Use um prompt assim:

Apply supabase-postgres-best-practices to this endpoint query. Check for missing composite or partial indexes, N+1 patterns, unnecessary scans, and pagination problems. If you suggest an index, explain why the predicate and sort order fit it. If EXPLAIN ANALYZE would change your confidence, say exactly what to verify.

Isso funciona melhor do que pedir apenas “best practices”, porque solicita decisões, não resumos.

Exemplo de prompt para revisão de schema e RLS

Para trabalho com schema ou policies, experimente:

Use the supabase-postgres-best-practices skill to review this migration and RLS policy set. Focus on foreign-key indexing, data types, constraints, lowercase identifiers, privilege boundaries, and whether the RLS predicates will scale on large tables. Return changes in priority order with SQL examples.

Esse prompt direciona o modelo para as áreas de referência mais fortes do repositório.

Melhores caminhos de leitura no repositório por tarefa

Use estes caminhos de arquivo como atalhos:

• query lenta: references/query-missing-indexes.md, references/query-composite-indexes.md, references/query-covering-indexes.md
• soft-delete ou carga filtrada: references/query-partial-indexes.md
• overfetching de API ou chamadas repetidas: references/data-n-plus-one.md, references/data-batch-inserts.md
• problemas de paginação: references/data-pagination.md
• filas de workers ou contenção: references/lock-skip-locked.md, references/lock-short-transactions.md
• auth do Supabase e performance de policies: references/security-rls-basics.md, references/security-rls-performance.md
• diagnóstico de lentidão: references/monitor-explain-analyze.md, references/monitor-pg-stat-statements.md

Esse é o caminho mais rápido para extrair valor prático de supabase-postgres-best-practices for Database Engineering.

Fluxo de trabalho recomendado em projetos reais

Um fluxo confiável é:

1. identificar a classe do problema
2. carregar apenas os arquivos de referência correspondentes
3. pedir uma lista priorizada de correções
4. solicitar reescritas de SQL e DDL de índices
5. validar com EXPLAIN ANALYZE ou com dados reais de carga
6. iterar sobre uma ou duas mudanças principais, e não sobre toda melhoria possível

A skill é mais forte quando usada como revisora focada, não como assistente ampla de brainstorming.

Dicas práticas que mudam a qualidade da saída

Algumas escolhas de uso fazem diferença perceptível:

• inclua os índices já existentes para o modelo não sugerir duplicatas
• inclua predicados de exemplo e cláusulas ORDER BY para que a recomendação de índice tenha o formato certo
• diga se há muita escrita, porque isso muda os tradeoffs de indexação
• para RLS, forneça o texto real das policies; caso contrário, a orientação de performance tende a ficar genérica
• peça “priority order” para que correções críticas venham antes de limpezas opcionais

FAQ da skill supabase-postgres-best-practices

supabase-postgres-best-practices é só para usuários de Supabase?

Não. A skill é mantida pela Supabase, mas a maior parte das orientações é conselho padrão de engenharia em Postgres. Ela continua útil se você roda Postgres vanilla, especialmente em planejamento de queries, indexação, locking, JSONB e busca full-text.

Essa skill é boa para iniciantes?

Pode ajudar iniciantes motivados, mas não foi feita com foco principal em iniciantes. Os exemplos são concretos e claros, porém muitas recomendações assumem que você consegue ler SQL, entender índices e validar planos. Se você é novo em Postgres, use a skill com contexto real de schema e peça explicações em linguagem simples junto com as correções.

O que essa skill faz melhor do que um prompt geral de SQL?

O supabase-postgres-best-practices guide oferece ao modelo um conjunto curado de anti-patterns, SQL corrigido, enquadramento de impacto e referências específicas por tema. Isso normalmente gera respostas mais acionáveis do que prompting genérico, especialmente em índices parciais, performance de RLS, limites de conexão e padrões de lock.

Quando eu não deveria usar supabase-postgres-best-practices?

Não espere que ela substitua benchmarking em produção, tuning de infraestrutura no nível de DBA ou orientação operacional específica de serviços gerenciados por fornecedor. Ela também não vai inferir sua carga de trabalho corretamente se você não fornecer detalhes de schema, query ou plano.

Ela ajuda em debugging de performance, não só em geração de código?

Sim. As referências de monitoramento cobrem EXPLAIN ANALYZE, pg_stat_statements e tópicos de vacuum/analyze, então a skill pode apoiar tanto o diagnóstico quanto a reescrita. Ela é útil tanto antes de escrever SQL quanto depois que você já observou lentidão.

Ela pode revisar migrations e pull requests?

Sim. Esse é um dos melhores usos. Ela pode inspecionar SQL de migration, diffs de schema, mudanças de policy e código de query em busca de prováveis problemas de performance ou segurança, e então propor alternativas mais alinhadas ao Postgres.

Como melhorar a skill supabase-postgres-best-practices

Dê à skill as evidências de que ela precisa

A forma mais rápida de melhorar a saída de supabase-postgres-best-practices é fornecer evidências concretas:

• EXPLAIN ANALYZE
• schemas de tabelas
• definições de índices
• contagem de linhas
• frequência das queries
• proporção de leitura/escrita
• definições de policies

Esta skill tem um material de referência forte, mas ainda assim não consegue escolher bem entre, por exemplo, um índice composto e um índice parcial se seus predicados não estiverem claros.

Peça correções priorizadas, não um despejo de conselhos

Um prompt forte é:

Apply supabase-postgres-best-practices and return the top 3 changes by expected impact, with exact SQL and verification steps.

Isso produz uma saída melhor do que “review everything”, porque o próprio repositório é organizado por impacto e prioridade de categoria.

Force recomendações conscientes de tradeoffs

Peça ao modelo para incluir:

• benefício esperado em leitura
• overhead de escrita
• custo de armazenamento
• risco de migração
• ressalvas operacionais

Isso é especialmente importante para índices extras, particionamento, covering indexes, indexação de JSONB e prepared statements.

Modos de falha comuns que você deve observar

Saídas de baixa qualidade normalmente incluem:

• sugerir índices sem checar padrões de filtro e ordenação
• recomendar particionamento cedo demais
• discutir correção de RLS, mas não performance de RLS
• propor conselhos de connection pooling sem considerar seu modelo de deploy
• reescrever SQL sem indicar como verificar se o plano realmente mudou

Quando isso acontecer, restrinja o escopo da tarefa e aponte para os arquivos de referência correspondentes.

Use os nomes dos arquivos de referência dentro do prompt

Você pode melhorar a precisão direcionando para documentos exatos, por exemplo:

Use references/query-partial-indexes.md and references/query-composite-indexes.md to decide which index strategy fits this workload.

ou

Apply the guidance from references/security-rls-performance.md to these policies and explain any index support they need.

Como o repositório é modular, prompts orientados por arquivo costumam gerar resultados melhores do que invocar a skill inteira de forma abstrata.

Itere após a primeira resposta com prompts de verificação

Depois de receber uma resposta inicial, faça perguntas de continuação como:

• “Qual recomendação tem a melhor relação impacto/risco?”
• “Mostre as diferenças exatas de EXPLAIN que eu devo esperar.”
• “Revise a recomendação de índice para uma carga com muita escrita.”
• “Reescreva isso para cursor pagination em vez de offset pagination.”
• “Verifique se o predicado de RLS consegue usar um índice.”

É nessa segunda rodada que o esforço de instalação e uso de supabase-postgres-best-practices install muitas vezes passa a valer ainda mais.

Melhore a saída para equipes de Database Engineering

Para fluxos de trabalho em equipe, padronize o template de prompt com base nos campos de que seus revisores realmente precisam:

• tabelas afetadas
• SQL atual e SQL proposto
• volume de carga
• meta de latência
• índices existentes
• RLS sim/não
• modelo de deploy
• risco de migração aceitável

Isso transforma o fluxo de supabase-postgres-best-practices for Database Engineering em uma ferramenta de revisão repetível, e não em um assistente ad hoc.

Se você for estender a skill por conta própria

Se você contribuir internamente ou upstream, siga o próprio padrão do repositório em references/_template.md e references/_contributing.md: mostre primeiro o padrão incorreto, depois o SQL corrigido, e inclua impacto quantificado. Essa estrutura é um dos motivos pelos quais a skill é útil para agentes em primeiro lugar.