Estándares de Revisión de Consultas

Las nuevas consultas SQL en los PRs de la aplicación necesitan el mismo rigor que la revisión de contratos de API. Requiere evidencia: EXPLAIN, estimaciones de filas y justificación de índices antes de fusionar a las rutas de producción.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT o.id, o.total
FROM orders o
WHERE o.customer_id = $1
  AND o.created_at >= now() - interval '90 days'
ORDER BY o.created_at DESC
LIMIT 50;

## Lista de Verificación de Revisión SQL de PR
- [ ] EXPLAIN adjuntado desde staging con estadísticas similares a producción
- [ ] Filas estimadas dentro de 10x de las reales (ANALYZE actual)
- [ ] Justificación de índice o prueba de que un escaneo secuencial es aceptable
- [ ] No usar SELECT * en rutas críticas
- [ ] Los tipos de parámetros coinciden con los tipos de columna (sin conversión implícita)

Cuándo usar esto: Cualquier PR que toque SQL del repositorio, consultas crudas de ORM, definiciones de informes o funciones generadas por migraciones.

Ejemplo de Trabajo

El desarrollador añade una consulta de panel que filtra orders por status y created_at.

-- Antes de fusionar: el revisor ejecuta en staging
EXPLAIN (ANALYZE, BUFFERS)
SELECT count(*) FROM orders
WHERE status = 'pending'
  AND created_at > '2026-01-01';
 
-- El plan muestra un escaneo secuencial en 12M de filas, 4.2s
-- El revisor solicita evidencia de índice
CREATE INDEX CONCURRENTLY orders_status_created_idx
  ON orders (status, created_at DESC);
 
EXPLAIN (ANALYZE, BUFFERS)
SELECT count(*) FROM orders
WHERE status = 'pending'
  AND created_at > '2026-01-01';
-- Escaneo de índice, 45ms

Lo que esto demuestra:

• Adjuntar planes antes y después al añadir índices.
• ANALYZE en staging después de cargas de datos grandes antes de confiar en las estimaciones.
• El orden de las columnas del índice multicolumna coincide con el patrón de filtro + ordenación.
• La migración para el índice se envía en un paso de despliegue separado cuando el nivel de riesgo lo requiere.

Análisis Profundo

Artefactos Requeridos en el PR

Sanidad de la Estimación de Filas

SELECT relname, last_analyze, last_autoanalyze, n_live_tup
FROM pg_stat_user_tables
WHERE relname = 'orders';

Si las estimaciones difieren en 100x, ejecuta ANALYZE orders (o corrige estadísticas extendidas) antes de aprobar el gasto en índices.

Cuándo un Escaneo Secuencial Está Bien

• Tablas de dimensión pequeñas (< 10k filas) consultadas una vez por solicitud.
• Informe de administración único con tiempo de espera de sentencia y horario fuera de horas pico.
• La consulta devuelve una gran fracción de la tabla donde el índice + la obtención del heap cuestan más.

Documenta el "escaneo secuencial aceptado" con prueba de recuento de filas en el comentario del PR.

ORM y N+1

-- Detectar patrón: 1 + N consultas en el rastro APM
-- Corregir: JOIN o WHERE id = ANY($1::bigint[])
SELECT * FROM line_items WHERE order_id = ANY($1::bigint[]);

Trampas Comunes

• EXPLAIN sin ANALYZE - Muestra solo estimaciones; oculta el tiempo de ejecución. Corrección: Requerir ANALYZE en staging para rutas críticas.
• Revisión contra tablas vacías - Escaneos de índice instantáneos en 0 filas. Corrección: Rellenar staging al 10-30% de los recuentos de filas de producción.
• Conversión implícita que mata el índice - WHERE created_at > $1 con parámetro de texto. Corrección: Coincidir tipos; convertir el parámetro, no la columna.
• Falta de LIMIT en ordenación - Ordena millones de filas para la página 1 de la interfaz de usuario. Corrección: Paginación por clave o filtros más estrictos.
• Nuevo índice por PR - La proliferación de índices ralentiza las escrituras. Corrección: Consolidar índices multicolumna; revisar Manejo de Solicitudes de Índices.

Alternativas

Preguntas Frecuentes

Relacionado

• Manejo de Solicitudes de Índices - aprobación de índices
• Conceptos Básicos de EXPLAIN - lectura de planes
• Revisión de Código para SQL - flujo de git
• pg_stat_statements - auditoría de producción

Versiones de Stack: Esta página fue escrita para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, y PostGIS 3.5+.