sql-optimization-patterns

Visão geral da skill sql-optimization-patterns

O que a sql-optimization-patterns faz

A skill sql-optimization-patterns ajuda um agente a diagnosticar SQL lento, explicar por que uma consulta está lenta e sugerir correções concretas relacionadas ao formato da query, indexação, joins, paginação e leitura de plano de execução. Ela é mais útil quando você já tem um problema real de performance e quer um fluxo estruturado de otimização, em vez de conselhos genéricos do tipo “adicione um índice”.

Quem deve instalar

Essa skill é indicada para engenheiros backend, engenheiros de banco de dados, times de plataforma e desenvolvedores de aplicações que precisam acelerar queries sem trabalhar no achismo. Ela é especialmente relevante para equipes que lidam com saída de EXPLAIN no estilo PostgreSQL, mas os padrões de raciocínio também se aplicam a outros bancos relacionais.

Trabalho real que ela resolve

Em geral, quem procura isso precisa de mais do que uma revisão de sintaxe. Precisa:

• identificar por que uma query está lenta
• relacionar sintomas do plano às causas-raiz mais prováveis
• decidir entre reescrever a query ou mudar índices
• evitar “correções” que aceleram uma consulta, mas pioram escrita ou consumo de armazenamento
• comunicar tradeoffs com clareza para o time

É nesse ponto que a sql-optimization-patterns entrega mais valor do que um prompt simples.

O que diferencia esta skill

O principal diferencial está na abordagem orientada a padrões. Ela não apenas diz “otimize o SQL”; ela direciona o agente para preocupações práticas de engenharia de banco de dados, como:

• leitura de EXPLAIN e EXPLAIN ANALYZE
• identificar scans sequenciais, joins mal escolhidos e paginação ineficiente
• escolher estratégias de índice de forma intencional
• lidar com anti-patterns comuns, como padrões de acesso N+1

Casos ideais e casos menos indicados

Melhor cenário:

• uma query lenta já conhecida
• um plano de execução que você possa colar
• detalhes de schema, índices e contexto de volume de linhas disponíveis
• trabalho de performance ligado à latência de API ou carga no banco

Cenário menos favorável:

• sem texto da query
• sem plano de execução
• perguntas puramente de arquitetura em nível de ORM, sem visibilidade do SQL
• tuning específico de fornecedor que depende de detalhes internos do engine não informados no prompt

Como usar a skill sql-optimization-patterns

Contexto de instalação da sql-optimization-patterns

O repositório não expõe um instalador customizado dentro de SKILL.md, então a instalação deve ser feita pelo seu fluxo de carregamento de skills para o repositório wshobson/agents. Depois disso, garanta que seu agente consiga acessar a skill chamada sql-optimization-patterns.

Se o seu ambiente usa o fluxo comum de Skills, o caminho prático é adicionar o repositório e depois invocar a skill pelo nome em uma tarefa que peça explicitamente uma análise de otimização SQL.

Leia este arquivo primeiro

Comece por:

• plugins/developer-essentials/skills/sql-optimization-patterns/SKILL.md

Esta skill é autocontida. Não há references/, rules/ ou scripts de apoio dentro da pasta da skill, então quase toda a orientação útil está concentrada nesse único arquivo. Isso é bom para adoção rápida, mas também significa que a qualidade da sua entrada pesa ainda mais.

Quais entradas a skill precisa

Para obter uma resposta forte, forneça ao agente:

• a query SQL
• engine e versão do banco, se souber
• schemas das tabelas ou colunas relevantes
• índices existentes
• ordem de grandeza do volume de linhas ou tamanho aproximado das tabelas
• a saída de EXPLAIN ou EXPLAIN ANALYZE
• o objetivo de negócio, como “reduzir a latência P95 do endpoint”

Sem dados de plano, o agente ainda pode sugerir padrões, mas as recomendações serão menos confiáveis.

Prompt mínimo viável

Um prompt funcional de sql-optimization-patterns usage se parece com isto:

Use the sql-optimization-patterns skill.

Database: PostgreSQL 15
Goal: reduce this query from 2.4s to under 200ms
Tables:
- users(id, email, created_at, status)
- orders(id, user_id, order_total, created_at)

Current indexes:
- users_pkey(id)
- orders_user_id_idx(user_id)

Query:
SELECT u.*, o.order_total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE u.created_at > NOW() - INTERVAL '30 days'
ORDER BY u.created_at DESC
LIMIT 100;

EXPLAIN ANALYZE:
[paste full plan]

Please identify likely bottlenecks, explain the plan, recommend query/index changes, and rank fixes by expected impact and risk.

Como transformar um pedido vago em um pedido forte

Pedido fraco:

Make this SQL faster.

Pedido forte:

Use sql-optimization-patterns for Database Engineering.

I need:
1. plan interpretation
2. likely root cause
3. index recommendations with rationale
4. query rewrite options
5. tradeoffs for write amplification and storage
6. a safe rollout order

Engine: PostgreSQL 14
Traffic pattern: read-heavy API endpoint
Data scale: users 8M rows, orders 120M rows
Current problem: endpoint P95 is 1.8s, DB CPU spikes during peak
Query: [paste]
Plan: [paste]
Existing indexes: [paste]

O segundo prompt funciona melhor porque dá à skill contexto operacional suficiente para priorizar correções, em vez de apenas listar dicas genéricas.

Fluxo prático que traz os melhores resultados com sql-optimization-patterns

Um bom fluxo é:

1. cole a query exata e o plano completo
2. peça ao agente para explicar, em linguagem simples, os maiores fatores de custo
3. peça 2 a 3 correções candidatas, não 10
4. solicite o ganho esperado e o lado negativo de cada uma
5. implemente primeiro a mudança de menor risco
6. rode EXPLAIN ANALYZE novamente
7. compare o antes e o depois

Isso mantém a skill sql-optimization-patterns ancorada em resultados mensuráveis, em vez de tuning especulativo.

Em que a skill sql-optimization-patterns é especialmente boa

O material de origem enfatiza fortemente:

• interpretação de EXPLAIN
• estratégia de índices
• análise de padrões de join
• eficiência de paginação
• problemas de query N+1

Na prática, isso faz da sql-optimization-patterns uma opção forte para otimização em nível de query e decisões de schema/índice, e não apenas para formatação de SQL.

O que pedir explicitamente

Para extrair respostas mais úteis em esforços de sql-optimization-patterns install e uso, peça ao agente:

• “qual é o maior gargalo deste plano”
• “se um novo índice ou uma reescrita da query é o melhor primeiro passo”
• “quais tipos de scan/join estão me prejudicando”
• “se a query pode se tornar index-only”
• “como essa mudança afeta writes, vacuum ou armazenamento”
• “o que medir depois do rollout”

Esses prompts forçam priorização, e isso muitas vezes é o que separa uma resposta útil de uma resposta barulhenta.

Bloqueios comuns na adoção

Os maiores bloqueios geralmente não são de instalação, mas de falta de evidência:

• saída de plano apenas parcial
• nenhuma informação sobre tamanho das tabelas
• índices atuais não listados
• SQL gerado por ORM colado sem contexto de negócio
• pedido de “boas práticas” em vez de diagnóstico de um caminho real

Se você só fornecer o texto da query, espere sugestões amplas. Se fornecer plano, schema e contexto de carga, a skill passa a ser muito mais útil para tomada de decisão.

Como interpretar a saída com segurança

Não trate todo índice sugerido como ganho garantido. Uma boa mentalidade ao usar um sql-optimization-patterns guide é validar:

• se os predicados de filtro ou join realmente combinam com a ordem do índice proposto
• se a query é seletiva o bastante para se beneficiar
• se um índice composto é melhor do que vários índices de uma coluna só
• se a correção ajuda uma query, mas prejudica a performance de insert/update

A skill é mais forte quando usada para gerar hipóteses que você consegue testar imediatamente.

FAQ da skill sql-optimization-patterns

Vale a pena instalar sql-optimization-patterns se eu já conheço SQL?

Sim, se você quer uma análise de otimização consistente sob pressão. O valor não está no conhecimento básico de SQL, e sim no conjunto estruturado de padrões para planos, tipos de scan, joins e escolhas de índice.

Esta skill sql-optimization-patterns é amigável para iniciantes?

Razoavelmente, mas iniciantes devem usá-la com exemplos reais. A skill fica muito mais clara quando você compara o texto da query com a saída de EXPLAIN ANALYZE. Se você ainda é novo em planos de execução, peça ao agente para definir cada nó importante em linguagem simples antes de recomendar mudanças.

Em que isso é melhor do que um prompt normal de IA?

Um prompt normal costuma devolver dicas genéricas de tuning. A sql-optimization-patterns skill é orientada para um fluxo repetível de otimização e para os sinais práticos que importam em engenharia de banco de dados, especialmente interpretação de plano e estratégia de índices.

Ela exige PostgreSQL?

Não, mas os exemplos têm claramente um viés de PostgreSQL. Se você usa MySQL, SQLite, SQL Server ou outro engine, informe o nome do banco e a saída equivalente de plano para que o agente adapte a orientação.

Quando eu não devo usar sql-optimization-patterns?

Não comece por aqui se o problema principal for:

• connection pooling
• contenção de locks sem evidência da query
• saturação de infraestrutura fora do banco
• ausência de estratégia de cache na aplicação
• mau uso de ORM que esconde o SQL real

Nesses casos, essa skill pode ajudar mais tarde, mas não é a primeira ferramenta a usar.

Ela pode ajudar com design de schema, e não só com uma query lenta?

Sim. A skill cobre estratégia de indexação e padrões de query escaláveis, então pode apoiar decisões de schema. Ainda assim, ela é mais eficaz quando está ligada a padrões de acesso, filtros esperados, joins, ordenações e volume de dados.

Como melhorar a skill sql-optimization-patterns

Dê evidências melhores para a sql-optimization-patterns

A forma mais rápida de melhorar os resultados é fornecer:

• texto completo da query, não uma paráfrase
• saída completa do plano, não apenas as primeiras linhas
• tempo real de EXPLAIN ANALYZE, quando for seguro
• índices existentes
• cardinalidade aproximada e contagem de linhas
• se a carga é mais de leitura ou mais de escrita

Evidência melhor gera recomendações mais críveis e menos índices irrelevantes.

Peça recomendações ranqueadas

A skill se torna mais útil quando você pede que ela classifique as correções por:

• impacto esperado na latência
• esforço de implementação
• risco operacional
• overhead de escrita
• reversibilidade

Esse ranqueamento ajuda o time a escolher uma ação, e não apenas acumular ideias.

Force a análise de tradeoffs

Um modo de falha comum é aceitar uma solução rápida para leitura que cria writes caros ou índices inchados. Melhore a saída da sql-optimization-patterns perguntando:

• “Qual é o custo desse índice em inserts e updates?”
• “Isso vai criar índices redundantes?”
• “Partitioning ou reescrita seria melhor do que mais um índice?”
• “Keyset pagination é melhor aqui do que offset pagination?”

Use iteração com antes e depois

Depois da primeira recomendação, rode o plano novamente e peça à skill para comparar:

• gargalo original
• novo gargalo
• o que melhorou
• o que continua caro
• se a próxima otimização ainda vale a pena

Essa é a forma mais confiável de transformar a skill em um ciclo de otimização, e não em uma resposta pontual.

Fique atento aos modos de falha comuns

Os erros mais frequentes são:

• otimizar sem dados de ANALYZE
• adicionar índices para filtros de baixa seletividade
• ignorar ordem de join e estimativas de cardinalidade
• reescrever SQL sem validar o novo plano
• focar em uma única query e deixar passar um padrão N+1 a montante

Você pode reduzir esses erros pedindo ao agente que explicite as suposições antes de sugerir mudanças.

Padrões de prompt que melhoram a qualidade da saída

Use prompts como:

Use the sql-optimization-patterns skill and do not give generic advice.
Base recommendations on the query plan provided.
For each proposed fix, explain:
1. why it should help
2. what plan node it targets
3. what tradeoff it introduces
4. how to validate it after deployment

Esse formato força o agente a conectar cada sugestão às evidências.

Como melhorar a adoção em equipe

Se você quer que essa skill ajude um time, padronize o template de entrada:

• engine/versão
• query
• schema
• índices
• plano
• tamanho das tabelas
• latência-alvo
• notas sobre a carga

Isso reduz variabilidade e torna sql-optimization-patterns for Database Engineering muito mais repetível entre incidentes e code reviews.