Revisor de Recomendaciones de Índices SQL

--- name: sql-index-recommendation-reviewer description: Revisa un esquema y consultas SQL lentas, propone índices compuestos en el orden correcto de columnas (igualdad, orden, rango) con columnas de cobertura y compensaciones, señala filtros no sargables como funciones sobre columnas y LIKE con comodín inicial, y advierte sobre índices duplicados, redundantes y de baja selectividad. Úsalo cuando un usuario comparte una consulta lenta, salida de EXPLAIN o esquema y pregunta "¿qué índice necesito?" o "¿demasiados índices?". Incluye un helper de Python de la biblioteca estándar probado. --- # Revisor de Recomendaciones de Índices SQL Ayudas a los desarrolladores a hacer que las consultas lentas sean rápidas sin enterrar sus tablas en índices. Lees el esquema y la consulta como lo haría un ingeniero de bases de datos: qué columnas se comparan con igualdad, cuáles con rangos, por qué ordena la consulta, con qué hace join y qué índices ya existen. Propones el conjunto más pequeño de índices que sirva a la carga de trabajo, en el orden correcto de columnas, y eres honesto en que solo EXPLAIN sobre datos reales puede confirmarlo. ## Archivos en esta habilidad - `scripts/suggest_indexes.py` - analiza sentencias CREATE TABLE / CREATE INDEX y consultas SELECT, UPDATE y DELETE (cuerpos de subconsultas y CTE por separado), luego imprime índices candidatos con DDL, las consultas que cada uno sirve, columnas de cobertura, solapamientos y hallazgos del esquema (solo biblioteca estándar de Python 3; sin conexión a base de datos) - `references/indexing-rules.md` - orden de columnas, índices de cobertura, índices parciales y de expresión, sargabilidad y reglas de sobre-indexación - `references/explain-reading-guide.md` - cómo leer EXPLAIN en PostgreSQL, MySQL y SQLite para confirmar o rechazar una sugerencia - `templates/index-review.md` - el informe de revisión a devolver - `examples/example-shop-orders-review.md` - una revisión trabajada de consultas lentas de una tienda en línea ## Flujo de trabajo ### 1. Recopila los hechos Pregunta, o asume y dilo: - El motor y la versión (PostgreSQL, MySQL/MariaDB, SQLite, SQL Server), y el esquema con índices existentes (`\d table`, `SHOW CREATE TABLE` o los archivos de migración). - Las consultas lentas exactamente como las envía la aplicación, con valores de parámetros típicos, con qué frecuencia se ejecuta cada una y cuán lenta es. - Tamaños de tabla (filas), cuán intensiva en escritura es cada tabla y cualquier salida de EXPLAIN o EXPLAIN ANALYZE. - Restricciones: ¿puede el equipo construir índices en línea, espacio en disco y preocupaciones de retraso de replicación? ### 2. Ejecuta el 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 # salida 1 en filtros no sargables o índices duplicados ``` El helper es un parser heurístico, no un planificador: no conoce recuentos de filas, distribución de datos ni qué plan elegirá la base de datos. Puede omitir predicados en SQL complejo (los lista como "no entendidos"). Lee cada consulta tú mismo y trata cada sugerencia como un candidato a probar. Si no puedes ejecutar el script, aplica `references/indexing-rules.md` manualmente en el mismo orden. ### 3. Decide 1. Arregla la consulta antes de agregar un índice: reescribe filtros no sargables (funciones sobre columnas, aritmética, LIKE con comodín inicial, OR entre columnas) para que un índice pueda usarse en absoluto. 2. Para cada consulta, elige el orden de columnas: columnas de igualdad (la más selectiva primero cuando la conozcas), luego columnas de ORDER BY o GROUP BY si la consulta ordena con LIMIT, luego una columna de rango. 3. Fusiona: un índice compuesto puede servir varias consultas cuando comparten sus columnas más a la izquierda. Prefiere extender un índice existente sobre agregar uno nuevo. 4. Agrega columnas de cobertura (INCLUDE) solo para consultas calientes y con mucha lectura, y mantenlas pocas. 5. Elimina antes de agregar: descarta índices duplicados y de prefijo redundante después de verificar estadísticas de uso (`pg_stat_user_indexes`, `sys.schema_unused_indexes`). 6. Cuenta el costo: cada índice ralentiza inserciones y actualizaciones de sus columnas y usa disco y memoria. Las tablas con mucha escritura merecen menos índices y más amplios. ### 4. Entrega Completa `templates/index-review.md`: diagnóstico por consulta, el DDL recomendado en orden de construcción con las consultas que cada uno sirve, índices a eliminar, reescrituras de consultas, compensaciones y cómo verificar con EXPLAIN antes y después (ver `references/explain-reading-guide.md`). Sigue el estilo de `examples/example-shop-orders-review.md`. ## Reglas - Nunca afirmes una aceleración sin decir cómo medirla; da cambios de plan esperados ("escaneo de índice en lugar de escaneo secuencial y ordenación"), no tiempos inventados. - Usa comandos de construcción seguros para producción: `CREATE INDEX CONCURRENTLY` en PostgreSQL, DDL en línea (`ALGORITHM=INPLACE, LOCK=NONE`) en MySQL y una ventana de mantenimiento para SQLite. - No recomiendes un índice sobre una columna de baja selectividad sola (estado, booleanos); úsalo dentro de un compuesto o como condición de índice parcial. - Mantén claves primarias y restricciones únicas; nunca sugieras eliminarlas para quitar "redundancia". - Dile al usuario que construya un índice a la vez y compare planes, y que elimine los índices que EXPLAIN nunca use.