Habilidad EXPLAIN Review

Lista de verificación de crítica de planes para PRs del equipo de aplicaciones en PostgreSQL 18.4 - flujo de trabajo estructurado que los agentes y humanos usan para aceptar o rechazar cambios de consulta con evidencia EXPLAIN.

Receta

## Habilidad EXPLAIN Review - Lista de verificación rápida
- [ ] EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) adjunto
- [ ] Se ejecuta en staging con estadísticas a escala de producción (ANALYZE reciente)
- [ ] Sin Seq Scan inesperado en tablas grandes
- [ ] Estimaciones de filas dentro de 10x de lo real (Filas de Planificación vs. Reales)
- [ ] Sin Sort en conjuntos de filas grandes sin soporte de índice LIMIT
- [ ] Recuento de búferes justificado para la frecuencia de la consulta

EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT o.id, o.total
FROM orders o
WHERE o.tenant_id = $1 AND o.status = 'open'
ORDER BY o.created_at DESC
LIMIT 50;

Cuándo invocar esta habilidad:

ORM o SQL escrito a mano en PR que toca una ruta crítica (hot path)
pgbadger/pg_stat_statements marcó regresión después del despliegue
El asesor sugirió un índice que necesita validación humana

Ejemplo de Trabajo

PR de Entrada: El queryset de Django añade OR entre valores de status.

EXPLAIN (ANALYZE, BUFFERS)
SELECT * FROM orders
WHERE tenant_id = $1 AND (status = 'open' OR status = 'pending');

Señales de FALLO en la salida:
  Seq Scan on orders  (cost=0..250000 rows=1200000)
  Buffers: shared read=180000
  Planning Rows: 50000  Actual Rows: 890000

Salida de la habilidad:

## Veredicto: FALLO
 
### Problemas
1. Seq Scan - el filtro en tenant_id + status debería usar un índice
2. Estimación de filas con 18x de diferencia - ejecutar ANALYZE orders
3. OR previene el uso simple de btree compuesto - considerar reescritura a IN (...)
 
### Corrección Sugerida
```sql
SELECT * FROM orders
WHERE tenant_id = $1 AND status IN ('open', 'pending');

Índice (si falta)

CREATE INDEX CONCURRENTLY idx_orders_tenant_status
  ON orders (tenant_id, status);


## Análisis Profundo

### Rúbrica de Aprobación/Rechazo

| Señal | Aprobación | Rechazo |
| --- | --- | --- |
| Ruta de acceso | Index Scan / Index Only Scan en filtro | Seq Scan > 10k filas |
| Join | Hash/Merge en conjuntos grandes con claves de equi-join | Bucle anidado con seq scan interno |
| Sort | Escaneo de heap Top-N con índice | Sort externo en millones |
| Buffers | Estable vs frecuencia de llamada | Lectura de tabla completa por solicitud |

### Adjuntos Requeridos en el PR

```sql
-- Contexto de escala de la tabla
SELECT relname, n_live_tup, pg_size_pretty(pg_relation_size(oid))
FROM pg_class c JOIN pg_stat_user_tables s ON s.relid = c.oid
WHERE relname = 'orders';

Frescura de las Estadísticas

SELECT relname, last_analyze, last_autoanalyze
FROM pg_stat_user_tables WHERE relname = 'orders';
ANALYZE orders;  -- staging antes de EXPLAIN si está desactualizado

Trampas Comunes

EXPLAIN sin ANALYZE - muestra un plan barato que miente en tiempo de ejecución. Solución: requerir ANALYZE en staging.
Tabla de staging vacía - escaneo de índice instantáneo en 0 filas. Solución: poblar staging o usar una instantánea de estadísticas de producción.
"Agregar índice" genérico - duplicado de un índice existente. Solución: diff de pg_indexes antes del DDL.
Ignorar costo de escritura - el índice ahorra lectura pero mata el SLA de INSERT. Solución: notar la tasa de escritura de la tabla en la salida.
EXPLAIN en producción en tablas críticas - toma bloqueos reales con algunas configuraciones. Solución: por defecto usar la política de staging.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
`auto_explain`	Muestrear planes en logs	Revisión de PR antes de fusionar
UI de planes de pganalyze	Monitoreo continuo	Revisión air-gapped
Sesión de emparejamiento (Pairing session)	Primer PR de autor junior	CRUD trivial de rutina

Preguntas Frecuentes

¿Aceptar bitmap heap scan en lugar de index scan?

Sí, cuando la selectividad es moderada y múltiples predicados se combinan. Fallar cuando el bitmap cubre la mayor parte de la tabla repetidamente a alto QPS.

¿Qué tan estricto con la deriva de la estimación de filas?

10x entre lo planificado y lo real activa la investigación de estadísticas o estadísticas extendidas. 2x puede ser aceptable en tablas volátiles.

¿La habilidad aprueba el DDL de índice de migración?

Lo recomienda; la Habilidad de Seguridad de Migración puntúa el riesgo de bloqueo antes de la fusión.

Relacionado

Conceptos Básicos de Habilidades de Agente - estructura de la habilidad
Conceptos Básicos de EXPLAIN - lectura de planes
Seq Scan vs Index Scan - rutas de acceso
Revisión de Código para SQL - requisitos de PR
Emparejamiento en PRs de Consultas - revisión en vivo

Versiones de Stack: Esta página fue escrita para PostgreSQL 18.4 y el cliente psql 18.4.

Receta

## Habilidad EXPLAIN Review - Lista de verificación rápida
- [ ] EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) adjunto
- [ ] Se ejecuta en staging con estadísticas a escala de producción (ANALYZE reciente)
- [ ] Sin Seq Scan inesperado en tablas grandes
- [ ] Estimaciones de filas dentro de 10x de lo real (Filas de Planificación vs. Reales)
- [ ] Sin Sort en conjuntos de filas grandes sin soporte de índice LIMIT
- [ ] Recuento de búferes justificado para la frecuencia de la consulta

EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT o.id, o.total
FROM orders o
WHERE o.tenant_id = $1 AND o.status = 'open'
ORDER BY o.created_at DESC
LIMIT 50;

Cuándo invocar esta habilidad:

ORM o SQL escrito a mano en PR que toca una ruta crítica (hot path)
pgbadger/pg_stat_statements marcó regresión después del despliegue
El asesor sugirió un índice que necesita validación humana

Ejemplo de Trabajo

PR de Entrada: El queryset de Django añade OR entre valores de status.

EXPLAIN (ANALYZE, BUFFERS)
SELECT * FROM orders
WHERE tenant_id = $1 AND (status = 'open' OR status = 'pending');

Señales de FALLO en la salida:
  Seq Scan on orders  (cost=0..250000 rows=1200000)
  Buffers: shared read=180000
  Planning Rows: 50000  Actual Rows: 890000

Salida de la habilidad:

## Veredicto: FALLO
 
### Problemas
1. Seq Scan - el filtro en tenant_id + status debería usar un índice
2. Estimación de filas con 18x de diferencia - ejecutar ANALYZE orders
3. OR previene el uso simple de btree compuesto - considerar reescritura a IN (...)
 
### Corrección Sugerida
```sql
SELECT * FROM orders
WHERE tenant_id = $1 AND status IN ('open', 'pending');

Índice (si falta)

CREATE INDEX CONCURRENTLY idx_orders_tenant_status
  ON orders (tenant_id, status);


## Análisis Profundo

### Rúbrica de Aprobación/Rechazo

| Señal | Aprobación | Rechazo |
| --- | --- | --- |
| Ruta de acceso | Index Scan / Index Only Scan en filtro | Seq Scan > 10k filas |
| Join | Hash/Merge en conjuntos grandes con claves de equi-join | Bucle anidado con seq scan interno |
| Sort | Escaneo de heap Top-N con índice | Sort externo en millones |
| Buffers | Estable vs frecuencia de llamada | Lectura de tabla completa por solicitud |

### Adjuntos Requeridos en el PR

```sql
-- Contexto de escala de la tabla
SELECT relname, n_live_tup, pg_size_pretty(pg_relation_size(oid))
FROM pg_class c JOIN pg_stat_user_tables s ON s.relid = c.oid
WHERE relname = 'orders';

Frescura de las Estadísticas

SELECT relname, last_analyze, last_autoanalyze
FROM pg_stat_user_tables WHERE relname = 'orders';
ANALYZE orders;  -- staging antes de EXPLAIN si está desactualizado

Trampas Comunes

EXPLAIN sin ANALYZE - muestra un plan barato que miente en tiempo de ejecución. Solución: requerir ANALYZE en staging.
Tabla de staging vacía - escaneo de índice instantáneo en 0 filas. Solución: poblar staging o usar una instantánea de estadísticas de producción.
"Agregar índice" genérico - duplicado de un índice existente. Solución: diff de pg_indexes antes del DDL.
Ignorar costo de escritura - el índice ahorra lectura pero mata el SLA de INSERT. Solución: notar la tasa de escritura de la tabla en la salida.
EXPLAIN en producción en tablas críticas - toma bloqueos reales con algunas configuraciones. Solución: por defecto usar la política de staging.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
`auto_explain`	Muestrear planes en logs	Revisión de PR antes de fusionar
UI de planes de pganalyze	Monitoreo continuo	Revisión air-gapped
Sesión de emparejamiento (Pairing session)	Primer PR de autor junior	CRUD trivial de rutina

Preguntas Frecuentes

¿Aceptar bitmap heap scan en lugar de index scan?

Sí, cuando la selectividad es moderada y múltiples predicados se combinan. Fallar cuando el bitmap cubre la mayor parte de la tabla repetidamente a alto QPS.

¿Qué tan estricto con la deriva de la estimación de filas?

10x entre lo planificado y lo real activa la investigación de estadísticas o estadísticas extendidas. 2x puede ser aceptable en tablas volátiles.

¿La habilidad aprueba el DDL de índice de migración?

Lo recomienda; la Habilidad de Seguridad de Migración puntúa el riesgo de bloqueo antes de la fusión.

Relacionado

Conceptos Básicos de Habilidades de Agente - estructura de la habilidad
Conceptos Básicos de EXPLAIN - lectura de planes
Seq Scan vs Index Scan - rutas de acceso
Revisión de Código para SQL - requisitos de PR
Emparejamiento en PRs de Consultas - revisión en vivo

Versiones de Stack: Esta página fue escrita para PostgreSQL 18.4 y el cliente psql 18.4.

Habilidad EXPLAIN Review

Buscar en la documentación

Habilidad EXPLAIN Review