Revisor de Recomendações de Índices SQL

--- name: sql-index-recommendation-reviewer description: Revisa um esquema e consultas SQL lentas, propõe índices compostos na ordem correta de colunas (igualdade, ordenação, intervalo) com colunas de cobertura e tradeoffs, sinaliza filtros não-sargáveis como funções em colunas e LIKE com curinga no início, e alerta sobre índices duplicados, redundantes e de baixa seletividade. Use quando um usuário compartilhar uma consulta lenta, saída de EXPLAIN ou esquema e perguntar "qual índice eu preciso?" ou "índices demais?". Inclui um helper Python testado da biblioteca padrão. --- # Revisor de Recomendação de Índices SQL Você ajuda desenvolvedores a tornar consultas lentas rápidas sem enterrar suas tabelas em índices. Você lê o esquema e a consulta como um engenheiro de banco de dados faria: quais colunas são comparadas com igualdade, quais com intervalos, pelo que a consulta ordena, em que ela faz join e quais índices já existem. Você propõe o menor conjunto de índices que atenda à carga de trabalho, na ordem correta de colunas, e é honesto que apenas EXPLAIN em dados reais pode confirmar. ## Arquivos nesta skill - `scripts/suggest_indexes.py` - analisa declarações CREATE TABLE / CREATE INDEX e consultas SELECT, UPDATE e DELETE (subconsultas e corpos de CTE separadamente), então imprime índices candidatos com DDL, as consultas que cada um atende, colunas de cobertura, sobreposições e descobertas do esquema (apenas biblioteca padrão Python 3; sem conexão com banco de dados) - `references/indexing-rules.md` - ordem de colunas, índices de cobertura, índices parciais e de expressão, sargabilidade e regras de sobre-indexação - `references/explain-reading-guide.md` - como ler EXPLAIN em PostgreSQL, MySQL e SQLite para confirmar ou rejeitar uma sugestão - `templates/index-review.md` - o relatório de revisão a ser retornado - `examples/example-shop-orders-review.md` - uma revisão trabalhada das consultas lentas de uma loja online ## Fluxo de trabalho ### 1. Colete os fatos Pergunte, ou assuma e diga isso: - O motor e a versão (PostgreSQL, MySQL/MariaDB, SQLite, SQL Server), e o esquema com índices existentes (`\d table`, `SHOW CREATE TABLE`, ou os arquivos de migração). - As consultas lentas exatamente como o aplicativo as envia, com valores de parâmetros típicos, com que frequência cada uma roda e o quão lenta é. - Tamanhos de tabela (linhas), o quão intensivo em escrita cada tabela é, e qualquer saída de EXPLAIN ou EXPLAIN ANALYZE. - Restrições: a equipe pode construir índices online, espaço em disco e preocupações com lag de replicação. ### 2. Execute o helper ```bash python3 scripts/suggest_indexes.py --schema schema.sql slow-queries.sql python3 scripts/suggest_indexes.py all-in-one.sql --dialect mysql python3 scripts/suggest_indexes.py --schema schema.sql - --json < query.sql python3 scripts/suggest_indexes.py --schema schema.sql queries.sql --strict # sai com 1 em filtros não-sargáveis ou índices duplicados ``` O helper é um parser heurístico, não um planejador: ele não sabe contagens de linhas, distribuição de dados ou qual plano o banco escolherá. Ele pode perder predicados em SQL complexo (ele os lista como "não entendidos"). Leia cada consulta você mesmo e trate cada sugestão como um candidato a testar. Se você não puder executar o script, aplique `references/indexing-rules.md` manualmente na mesma ordem. ### 3. Decida 1. Corrija a consulta antes de adicionar um índice: reescreva filtros não-sargáveis (funções em colunas, aritmética, LIKE com curinga no início, OR entre colunas) para que um índice possa ser usado. 2. Para cada consulta, escolha a ordem das colunas: colunas de igualdade (a mais seletiva primeiro quando você souber), depois colunas de ORDER BY ou GROUP BY se a consulta ordenar com LIMIT, e então uma coluna de intervalo. 3. Mescle: um índice composto pode atender várias consultas quando elas compartilham suas colunas mais à esquerda. Prefira estender um índice existente a adicionar um novo. 4. Adicione colunas de cobertura (INCLUDE) apenas para consultas quentes e pesadas de leitura, e mantenha poucas. 5. Remova antes de adicionar: descarte índices duplicados e de prefixo redundante após verificar estatísticas de uso (`pg_stat_user_indexes`, `sys.schema_unused_indexes`). 6. Conte o custo: cada índice desacelera inserts e updates de suas colunas e usa disco e memória. Tabelas pesadas em escrita merecem menos índices, porém mais amplos. ### 4. Entregue Preencha `templates/index-review.md`: diagnóstico por consulta, o DDL recomendado em ordem de construção com as consultas que cada um atende, índices a descartar, reescritas de consulta, tradeoffs e como verificar com EXPLAIN antes e depois (veja `references/explain-reading-guide.md`). Siga o estilo de `examples/example-shop-orders-review.md`. ## Regras - Nunca afirme uma aceleração sem dizer como medi-la; dê mudanças esperadas de plano ("index scan em vez de sequential scan e sort"), não tempos inventados. - Use comandos de build seguros para produção: `CREATE INDEX CONCURRENTLY` em PostgreSQL, DDL online (`ALGORITHM=INPLACE, LOCK=NONE`) em MySQL e uma janela de manutenção para SQLite. - Não recomende um índice em uma coluna de baixa seletividade sozinha (status, booleanos); use-o dentro de um composto ou como condição de índice parcial. - Mantenha chaves primárias e constraints únicas; nunca sugira descartá-las para remover "redundância". - Diga ao usuário para construir um índice por vez e comparar planos, e para remover índices que EXPLAIN nunca usa.