Formateador SQL

Qué hace el formateador

• Las cláusulas (SELECT, FROM, WHERE, GROUP BY, ORDER BY, SET, VALUES, RETURNING…) empiezan cada una una línea; su contenido va con sangría debajo, un elemento por línea en las listas.
• Los joins empiezan una línea a nivel de cláusula; la condición ON se queda con el join y los términos AND/OR adicionales van con sangría debajo.
• Las subconsultas y los CTE abren un bloque entre paréntesis cuyo contenido lleva un nivel de sangría; las listas cortas entre paréntesis (IN ('a', 'b'), argumentos de función, tuplas) se quedan en una línea.
• Las expresiones CASE ponen cada WHEN y el ELSE en su propia línea y alinean END con CASE.
• Las funciones de ventana mantienen OVER (PARTITION BY … ORDER BY …) en una línea cuando cabe.
• CREATE TABLE escribe una definición de columna por línea; INSERT … VALUES escribe una tupla por línea.
• Las sentencias se separan con una línea en blanco tras cada punto y coma.

Lo que nunca toca

Los literales de cadena ('it''s', E'\n', $$ … $$), los identificadores entrecomillados ("Name", `name`, [name]), los comentarios (--, #, /* */) y los parámetros (?, $1, :name, @var) se copian byte a byte. Solo cambian los espacios en blanco y la caja de las palabras clave, así que la consulta formateada es la misma consulta. El cambio de caja se aplica a las palabras clave SQL y a las funciones estándar (COUNT, COALESCE, NOW…), no a tus propios identificadores: my_table sigue siendo my_table incluso en modo mayúsculas.

Comas al final o al principio

Las comas al final (a, al terminar una línea) son lo que producen la mayoría de las guías de estilo y los ORM. Las comas al principio (, b al empezar) permiten comentar cualquier línea de una lista de select salvo la primera sin romper la consulta, por eso son populares en SQL analítico. Elige la que tu equipo lea más rápido; el formateador convierte entre ambas.

Minificar

Minificar colapsa todo en una línea con espacios simples, convirtiendo los comentarios de línea en comentarios de bloque para que sobrevivan. Úsalo para líneas de registro, parámetros de URL o para pegar una consulta en un chat sin que se coman los saltos de línea.

Dialectos

El tokenizador entiende PostgreSQL (casts ::, parámetros $1, dollar quoting, operadores JSON ->>, FILTER, RETURNING, ON CONFLICT), MySQL/MariaDB (identificadores con acento grave, comentarios #, STRAIGHT_JOIN, ON DUPLICATE KEY UPDATE, LIMIT x OFFSET y), SQLite y SQL Server (identificadores [entre corchetes], @variables, TOP, CROSS APPLY). No valida el SQL; una consulta con un error de sintaxis se formatea lo mejor posible para que aún puedas leerla.

Formatear SQL en otros sitios

# PostgreSQL: pg_format (pgFormatter, Perl)
pg_format -s 2 -u 1 query.sql

# cualquier dialecto: sqlfluff (Python), también hace lint
sqlfluff fix --dialect postgres query.sql

# JavaScript: sql-formatter
npx sql-formatter -l postgresql query.sql

Preguntas