Formateador SQL

Por qué el formato afecta a la revisión de código, no al rendimiento

El planificador de consultas de PostgreSQL o MySQL ignora por completo los espacios, saltos de línea y mayúsculas: select * from pedidos y SELECT *\nFROM pedidos generan el mismo plan de ejecución. El formato importa exclusivamente para humanos: en un pull request, una consulta con cada JOIN en su propia línea y las condiciones de WHERE alineadas permite detectar en segundos un LEFT JOIN que debería ser INNER JOIN, o un filtro que falta en una subconsulta. Es la misma razón por la que se formatea JavaScript con Prettier: no cambia el comportamiento, cambia la velocidad de revisión.

Mayúsculas en palabras clave: convención, no obligación

SQL no distingue mayúsculas de minúsculas en sus palabras reservadas (select y SELECT son idénticos para el parser), pero la convención mayoritaria en la industria desde los años 80 es escribir en mayúsculas las palabras clave del lenguaje (SELECT, FROM, WHERE, AND, ORDER BY) y en minúsculas los identificadores propios del esquema (nombres de tabla y columna). Esto crea un contraste visual inmediato entre lo que es sintaxis SQL y lo que es dato del negocio, algo que ayuda especialmente cuando conviven consultas SQL con nombres de columnas en camelCase provenientes de un ORM.

Indentación de JOIN y subconsultas anidadas

Una consulta con tres o cuatro JOIN seguidos y sin indentación clara obliga a leer letra por letra para saber qué tabla se une con cuál. El formato estándar coloca cada JOIN ... ON ... en su propia línea, alineado con el FROM, y las subconsultas se indentan un nivel adicional respecto a la consulta que las contiene, con el paréntesis de cierre alineado con el de apertura. Por ejemplo, una subconsulta correlacionada en el WHERE para calcular el total de pedidos por cliente debe verse claramente anidada un nivel más adentro que el SELECT principal, no pegada al margen izquierdo como si fuera parte del nivel superior.

CTE (WITH) frente a subconsultas anidadas para legibilidad

Una Common Table Expression con WITH nombre AS (...) declara un resultado intermedio con nombre antes de la consulta principal, evitando anidar subconsultas dentro de subconsultas. Reescribir una consulta con tres niveles de subconsultas anidadas como una cadena de CTEs (WITH ventas_mes AS (...), ventas_por_region AS (...) SELECT ...) no cambia el resultado pero reduce drásticamente el esfuerzo de lectura, porque cada bloque puede entenderse de forma aislada y con nombre propio, similar a extraer funciones auxiliares en código de aplicación.

Formateo de INSERT y UPDATE con muchas columnas

En un INSERT INTO clientes (id, nombre, email, telefono, direccion) VALUES (...) con más de cuatro o cinco columnas, listar cada columna en su propia línea evita el error clásico de desalinear el orden de columnas respecto al orden de valores en un INSERT multi-fila. Lo mismo aplica a un UPDATE con múltiples asignaciones en SET: separar cada columna = valor en su propia línea permite detectar de un vistazo si falta una coma o si dos condiciones del WHERE deberían combinarse con AND en lugar de aparecer una debajo de otra sin operador.

Diferencias de dialecto entre PostgreSQL, MySQL y SQL Server

Un formateador genérico no puede asumir el mismo dialecto para todos los motores: PostgreSQL soporta ILIKE, RETURNING y operadores de rango (&&, <@) que MySQL no reconoce; MySQL usa comillas invertidas para identificadores (` pedido ) donde PostgreSQL usa comillas dobles; SQL Server antepone TOP n en el SELECT en lugar de LIMIT n` al final. Formatear correctamente implica reconocer estas particularidades sin reescribir la sintaxis a otro dialecto, algo que un formateador de propósito general basado solo en tokens genéricos de SQL a veces pasa por alto.

Formatear sin romper cadenas literales ni comentarios

Un formateador ingenuo basado en búsqueda y reemplazo de texto puede corromper una cadena literal que contenga la palabra from o where dentro de un valor de texto, por ejemplo WHERE descripcion = 'Envío from Madrid'. Un formateador correcto necesita un tokenizador real que distinga cadenas entre comillas simples, comentarios -- o /* */, e identificadores entre comillas dobles, aplicando las reglas de indentación solo a los tokens de sintaxis SQL y dejando intacto el contenido literal.

Salidas reales de ejemplo

select p.id, p.total, c.nombre, c.email from pedidos p join clientes c on c.id = p.cliente_id where p.estado = 'pagado' and p.fecha >= '2024-01-01' order by p.fecha desc limit 50;

SELECT
  p.id,
  p.total,
  c.nombre,
  c.email
FROM pedidos p
JOIN clientes c
  ON c.id = p.cliente_id
WHERE p.estado = 'pagado'
  AND p.fecha >= '2024-01-01'
ORDER BY p.fecha DESC
LIMIT 50;

WITH ventas_por_cliente AS (
  SELECT cliente_id, SUM(total) AS total_gastado
  FROM pedidos
  WHERE estado = 'pagado'
  GROUP BY cliente_id
)
SELECT c.nombre, v.total_gastado
FROM clientes c
JOIN ventas_por_cliente v
  ON v.cliente_id = c.id
WHERE v.total_gastado > 1000
ORDER BY v.total_gastado DESC;

INSERT INTO clientes (
  id,
  nombre,
  email,
  telefono,
  direccion
)
VALUES (
  gen_random_uuid(),
  'Ana Torres',
  'ana@example.com',
  '600111222',
  'Calle Mayor 4, Madrid'
);

Casos de uso comunes

• Normalizar el estilo de las consultas SQL antes de un pull request en un equipo con varios autores.
• Reformatear consultas heredadas de una sola línea extraídas de logs lentos para poder revisarlas.
• Convertir subconsultas anidadas en CTEs con nombre para facilitar el mantenimiento posterior.
• Preparar consultas legibles para incluir en documentación técnica o runbooks de incidencias.
• Revisar visualmente un INSERT o UPDATE con muchas columnas antes de ejecutarlo en producción.

Buenas prácticas

• Formatea antes de pedir revisión de código, no después: ahorra rondas de comentarios triviales sobre estilo.
• Usa mayúsculas para palabras clave y minúsculas para identificadores del esquema, de forma consistente en todo el proyecto.
• Prefiere CTEs con nombre sobre subconsultas anidadas más de dos niveles.
• Integra un linter de SQL (como sqlfluff) en CI para que el formato no dependa de la disciplina individual.
• No confíes en un formateador que no distinga cadenas literales de sintaxis: verifica que no altera valores de texto con palabras reservadas dentro.

Referencias oficiales

• PostgreSQL – SQL Syntax
• MySQL – SQL Statement Syntax
• sqlfluff – Documentación oficial