Formateador SQL
Formatea y embellece consultas SQL. Pega SQL desordenado y obtiene una salida limpia e indentada con resaltado de sintaxis.
Caracteristicas principales
- Conversión automática de palabras clave a mayúsculas
- Sangría configurable
- Resaltado de sintaxis
- Soporte para los dialectos SQL comunes
Guide
El formateo SQL transforma consultas densas e ilegibles en código estructurado, con sangría consistente que es fácil de leer, revisar, depurar y mantener. Una consulta que funciona perfectamente cuando se escribe como una sola línea se convierte en una carga de mantenimiento cuando otra persona (o tú, tres meses después) necesita entender lo que hace. El formateo SQL consistente no es cosmético. Reduce errores, acelera la revisión de código y hace que las consultas complejas sean manejables. Esta guía cubre convenciones de formateo, estructura de cláusulas, patrones comunes para diferentes tipos de consulta y cómo el formateo interactúa con la optimización de consultas. La regla fundamental del formateo SQL es una cláusula por línea. SELECT, FROM, WHERE, JOIN, ON, GROUP BY, HAVING, ORDER BY, LIMIT, INSERT INTO, VALUES, UPDATE, SET y DELETE FROM comienzan cada uno en su propia línea en el nivel de sangría base. Esta estructura hace que la consulta sea escaneable. Puedes ver de un vistazo qué columnas se seleccionan, qué tablas están involucradas, qué condiciones filtran los datos y cómo se ordenan los resultados. Una consulta formateada de esta manera se lee como un documento estructurado en lugar de una frase interminable. El formateo de la cláusula SELECT lista cada columna en su propia línea, con sangría de un nivel desde la palabra clave SELECT. Las comas iniciales (comas al principio de cada línea en lugar de al final) son una convención popular porque facilitan comentar columnas individuales y producen diffs más limpios en el control de versiones. Tanto las comas finales como las iniciales son aceptables siempre que la elección sea consistente en toda la base de código. Los alias de columna deberían usar la palabra clave AS explícitamente (column_name AS alias) en lugar de la abreviatura (column_name alias) para mayor claridad. Cuando una expresión de columna es larga (una declaración CASE o una llamada a función con múltiples argumentos), colócala en su propia línea y aplica sangría a la continuación. Las cláusulas FROM y JOIN se benefician de una alineación consistente. Cada JOIN obtiene su propia línea en la misma sangría que FROM. La condición ON se sangra debajo de su JOIN. Para consultas con muchas uniones, esta estructura visual hace que las relaciones entre tablas sean claras: FROM orders o JOIN customers c ON c.customer_id = o.customer_id JOIN products p ON p.product_id = o.product_id LEFT JOIN shipping s ON s.order_id = o.order_id El tipo de unión (INNER JOIN, LEFT JOIN, RIGHT JOIN, CROSS JOIN, FULL OUTER JOIN) transmite significado. El formateo que separa visualmente cada unión ayuda a los revisores a verificar que se usa el tipo de unión correcto para cada relación. Un LEFT JOIN que debería ser un INNER JOIN (o viceversa) es un error común que el código formateado hace más fácil de detectar. El formateo de la cláusula WHERE coloca cada condición en su propia línea con AND u OR al principio de la línea. Sangrar las condiciones debajo de WHERE hace que la lógica de filtro sea visible: WHERE o.order_date >= '2026-01-01' AND o.status = 'completed' AND c.country = 'US' AND (p.category = 'electronics' OR p.category = 'appliances') La lógica booleana compleja con operadores AND y OR mezclados es una fuente común de errores. El formateo con paréntesis explícitos y sangría clara muestra la agrupación lógica. Sin formateo, WHERE a = 1 AND b = 2 OR c = 3 es ambiguo para los lectores humanos (aunque SQL evalúa AND antes que OR, así que significa (a = 1 AND b = 2) OR c = 3). Formateado con paréntesis, la intención queda clara. Usa siempre paréntesis con AND/OR mezclados para hacer explícita la precedencia. Las subconsultas deberían sangrarse un nivel dentro de sus paréntesis. Cada subconsulta se formatea usando las mismas reglas que una consulta de nivel superior. Las subconsultas correlacionadas (aquellas que hacen referencia a columnas de la consulta externa) son particularmente importantes de formatear claramente porque su relación con la consulta externa determina su comportamiento: SELECT customer_name , total_spent FROM customers c WHERE total_spent > ( SELECT AVG(total_spent) FROM customers WHERE country = c.country ) La sangría muestra que la subconsulta está anidada dentro de la cláusula WHERE y hace referencia a c.country de la consulta externa. Para subconsultas profundamente anidadas (tres o más niveles), considera refactorizar a CTEs en su lugar, ya que el anidamiento profundo se vuelve difícil de seguir independientemente del formateo. Las Expresiones de Tabla Común (CTEs) usando cláusulas WITH deberían formatearse con cada CTE como un bloque nombrado separado: WITH monthly_sales AS ( SELECT DATE_TRUNC('month', order_date) AS month , SUM(amount) AS total FROM orders GROUP BY DATE_TRUNC('month', order_date) ), monthly_avg AS ( SELECT AVG(total) AS avg_total FROM monthly_sales ) SELECT m.month , m.total , a.avg_total FROM monthly_sales m CROSS JOIN monthly_avg a WHERE m.total > a.avg_total Las CTEs son una de las características SQL más potentes para dividir consultas complejas en componentes legibles y comprobables. Cada CTE puede probarse independientemente ejecutando solo su declaración SELECT. El formateo adecuado hace que el propósito de cada CTE sea visible y el flujo de datos entre CTEs rastreable. Nombra tus CTEs de forma descriptiva: monthly_sales es mejor que cte1. Las cláusulas GROUP BY y ORDER BY siguen el mismo patrón de múltiples líneas que SELECT cuando hacen referencia a múltiples columnas. Lista cada columna en su propia línea con sangría. Para GROUP BY, esto facilita verificar que todas las columnas SELECT no agregadas estén incluidas (un requisito en SQL estándar y aplicado por PostgreSQL, aunque MySQL es permisivo por defecto). Para ORDER BY, listar cada columna de ordenación con su dirección (ASC o DESC) en una línea separada aclara la prioridad de ordenación. Indicar ASC explícitamente (aunque sea el valor por defecto) mejora la legibilidad. El formateo de la cláusula HAVING sigue las mismas reglas que WHERE. HAVING filtra grupos después de la agregación, y sus condiciones deberían formatearse con una condición por línea. Un error común de formateo es colocar condiciones HAVING en la cláusula WHERE o viceversa. WHERE filtra filas antes de la agrupación. HAVING filtra grupos después de la agregación. La colocación correcta es esencial tanto para la corrección como para el rendimiento, y un formateo claro facilita la verificación. Las expresiones CASE son construcciones de múltiples líneas que deberían formatearse para mostrar cada par WHEN/THEN: SELECT order_id , CASE WHEN status = 'shipped' THEN 'In Transit' WHEN status = 'delivered' THEN 'Complete' WHEN status = 'returned' THEN 'Returned' ELSE 'Processing' END AS status_label FROM orders Las expresiones CASE anidadas (CASE dentro de CASE) deberían evitarse cuando sea posible porque se vuelven ilegibles independientemente del formateo. Refactoriza en CTEs, columnas calculadas o una tabla de búsqueda unida a la consulta en su lugar. Las declaraciones INSERT tienen dos formatos comunes. Para inserciones de una sola fila con columnas nombradas, lista cada par columna-valor de forma legible: INSERT INTO customers ( customer_name , email , country , created_at ) VALUES ( 'John Doe' , 'john@example.com' , 'US' , CURRENT_TIMESTAMP ) Alinear las entradas VALUES con sus correspondientes nombres de columna facilita verificar que cada valor coincide con la columna correcta. Para declaraciones INSERT...SELECT, formatea la porción SELECT usando las reglas estándar de formateo SELECT. Las declaraciones UPDATE se benefician de formatear cada asignación SET en su propia línea: UPDATE customers SET email = 'newemail@example.com' , updated_at = CURRENT_TIMESTAMP , status = 'verified' WHERE customer_id = 12345 Esta estructura deja claro qué columnas se están modificando y evita omitir accidentalmente la cláusula WHERE, lo cual actualizaría cada fila de la tabla. La cláusula WHERE en las declaraciones UPDATE y DELETE es la cláusula más crítica de acertar. El formateo que coloca WHERE en su propia línea al mismo nivel que UPDATE o DELETE hace que su presencia (o ausencia) sea obvia. Las declaraciones DELETE deberían tener siempre su cláusula WHERE claramente visible: DELETE FROM order_items WHERE order_id = 12345 AND item_status = 'cancelled' Un DELETE sin WHERE elimina todas las filas de la tabla. El código formateado hace que la presencia o ausencia de WHERE sea inmediatamente visible. Algunos equipos adoptan una convención de escribir siempre primero las consultas DELETE como consultas SELECT (reemplazando DELETE FROM con SELECT * FROM) para verificar qué filas se verán afectadas, y luego convertirlas de vuelta a DELETE. Las funciones ventana están entre las construcciones SQL más complejas de formatear. La cláusula OVER con PARTITION BY y ORDER BY debería estar en sus propias líneas con sangría cuando son largas: SELECT customer_id , order_date , amount , SUM(amount) OVER ( PARTITION BY customer_id ORDER BY order_date ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW ) AS running_total FROM orders Para especificaciones de ventana cortas, mantenerlas en una línea es aceptable: ROW_NUMBER() OVER (ORDER BY id) AS row_num. El objetivo es la legibilidad a la longitud y complejidad de la expresión real. Las definiciones de ventana nombradas (WINDOW w AS (PARTITION BY customer_id ORDER BY order_date)) seguidas de OVER w reducen la repetición cuando múltiples columnas usan la misma especificación de ventana. La capitalización de palabras clave es una elección de estilo con opiniones fuertes en ambos lados. Las palabras clave en MAYÚSCULAS (SELECT, FROM, WHERE) distinguen visualmente la sintaxis SQL de los nombres de tablas y columnas. Las palabras clave en minúsculas se mezclan pero son más fáciles de escribir. Lo más importante es la consistencia. Elige una convención y aplícala en todo el equipo. Muchas organizaciones usan mayúsculas para palabras clave y minúsculas para identificadores. Algunas guías de estilo modernas prefieren todo en minúsculas, argumentando que el resaltado de sintaxis en los editores ya distingue las palabras clave de los identificadores. Un tercer enfoque capitaliza solo las palabras clave principales de cláusula (SELECT, FROM, WHERE) y deja los nombres de función y las palabras clave secundarias en minúsculas. Los alias de tabla deberían ser significativos. Usar alias de una sola letra (a, b, c) ahorra escritura pero hace que las consultas sean más difíciles de leer, especialmente con muchas uniones. Las abreviaturas cortas derivadas del nombre de la tabla son mejores: customers AS c, orders AS o, order_items AS oi. En consultas complejas con muchas tablas, los alias más largos mejoran la claridad: customers AS cust, order_items AS items. Usa siempre la palabra clave AS para los alias para distinguirlos de errores tipográficos o comas olvidadas. Nunca uses palabras reservadas como alias. El ancho de sangría debería ser consistente. Dos espacios y cuatro espacios son ambas elecciones comunes. Tabuladores frente a espacios es una preferencia, pero los espacios producen una alineación más consistente entre editores y herramientas. La herramienta de formateo SQL te permite configurar el ancho de sangría para que coincida con el estándar de tu equipo. Sea cual sea el ancho que elijas, úsalo uniformemente para todos los niveles de sangría: cuerpo de cláusula, anidamiento de subconsultas, cuerpos de expresión CASE y definiciones de CTE. El formateo de comentarios en SQL usa -- para comentarios de una sola línea y /* */ para comentarios de múltiples líneas. Coloca los comentarios encima de la cláusula o expresión que describen, no en línea al final de una línea larga donde podrían pasarse por alto. Para la lógica de negocio compleja en cláusulas WHERE, un comentario que explique por qué existe una condición es valioso: -- Excluir cuentas de prueba creadas por el equipo de QA antes de la condición de filtro. Los comentarios que repiten el SQL (-- Unir tabla de clientes) añaden ruido sin valor. Los buenos comentarios explican la intención, no la mecánica. El formateo y el rendimiento de las consultas no están directamente relacionados. El motor de la base de datos analiza y optimiza la consulta independientemente de los espacios en blanco y los saltos de línea. Sin embargo, las consultas bien formateadas son más fáciles de optimizar porque puedes ver la estructura claramente. Una consulta mal formateada con un problema de rendimiento oculta el problema en un muro de texto. La misma consulta, adecuadamente formateada, revela la subconsulta problemática, la condición de unión faltante, el DISTINCT innecesario o la cláusula WHERE no apta para índices de un vistazo. El formateo es una herramienta de depuración y optimización. El control de versiones y el formateo SQL interactúan de formas importantes. Reformatear una consulta entera en un único commit produce un diff que toca cada línea, haciendo imposible ver qué cambió realmente. Al adoptar un formateador para una base de código existente, haz el formateo en un commit dedicado con un mensaje claro como "Aplicar estándar de formateo SQL". Los cambios posteriores entonces producen diffs limpios y significativos. Las comas iniciales son populares en parte porque añadir una nueva columna a un SELECT produce un diff de una línea (la nueva línea), mientras que las comas finales exigen modificar la línea anterior para añadir una coma, creando un diff de dos líneas. Las diferencias de dialecto afectan a las elecciones de formateo. PostgreSQL, MySQL, SQL Server, Oracle, SQLite y BigQuery tienen cada uno variaciones de sintaxis. PostgreSQL usa conversión con doble dos puntos (value::type) y cadenas entre comillas dolar. MySQL usa comillas inversas para identificadores y LIMIT con OFFSET. SQL Server usa comillas con corchetes, TOP en lugar de LIMIT y CROSS APPLY en lugar de LATERAL JOIN. Oracle usa ROWNUM, CONNECT BY para consultas jerárquicas y funciones de fecha diferentes. BigQuery usa comillas inversas para nombres de tabla cualificados por proyecto. Un formateador debería manejar el dialecto que tu equipo usa. La herramienta de formateo SQL soporta sintaxis SQL estándar que es compatible con todos los dialectos principales. La adopción por el equipo de estándares de formateo SQL exige una configuración compartida e idealmente una aplicación automatizada. Incluye reglas de formateo SQL en tu guía de estilo de código. Usa hooks de pre-commit o comprobaciones de CI para verificar el formateo en archivos SQL. Define el estándar en un archivo de configuración de herramienta (como .sql-formatter.json) que se confirma en el repositorio. El coste inicial de acordar un estándar se compensa a través de cada revisión de código que ya no incluye discusiones de formateo y cada sesión de depuración que empieza con código legible en lugar de un ejercicio de reformateo. El SQL en el código de la aplicación (incrustado en Python, JavaScript, Java u otros lenguajes) plantea desafíos adicionales de formateo. Una cadena SQL en bruto dentro de una función de Python o un literal de plantilla de JavaScript está sujeta tanto a las reglas de formateo del lenguaje anfitrión como a las reglas de formateo SQL. Los literales de cadena de múltiples líneas (triples comillas en Python, comillas inversas en JavaScript) te permiten mantener el formateo SQL dentro del código de la aplicación. Separa la cadena SQL de la lógica de la aplicación: asigna la consulta a una constante nombrada (const FIND_ACTIVE_USERS = ...) y haz referencia a ella donde se necesite. Para grandes colecciones de consultas, mueve el SQL a archivos .sql separados y cárgalos en tiempo de ejecución. El SQL generado por ORM a menudo necesita formateo para depuración. Cuando tu consulta de Django, SQLAlchemy, ActiveRecord o Prisma produce resultados inesperados, ver el SQL generado ayuda a diagnosticar el problema. La mayoría de los ORMs proporcionan una forma de sacar el SQL en bruto (query.toString() en Knex, str(query) en SQLAlchemy, .explain() en Django). Pega el SQL generado en un formateador para entender su estructura. El SQL generado por ORM es típicamente denso y difícil de leer porque nunca estuvo destinado a humanos. La salida formateada hace que las uniones, condiciones y subconsultas sean visibles. Los procedimientos almacenados y las funciones exigen disciplina de formateo más allá de las consultas individuales. Cada procedimiento contiene múltiples declaraciones SQL, declaraciones de variables, flujo de control (IF/ELSE, WHILE, FOR) y manejo de excepciones (TRY/CATCH, BEGIN/EXCEPTION). Formatea cada declaración SQL dentro del procedimiento usando las reglas estándar de formateo de consultas. Sangra los cuerpos de flujo de control un nivel desde sus palabras clave. Coloca BEGIN y END en sus propias líneas. Añade líneas en blanco entre secciones lógicas dentro del procedimiento. Los procedimientos almacenados bien formateados son drásticamente más fáciles de depurar que los densos y sin formatear. Los archivos de migración se benefician del formateo SQL porque se revisan en pull requests y representan cambios permanentes en el esquema de la base de datos. Una declaración CREATE TABLE con definiciones de columna formateadas es fácil de revisar para los tipos de datos correctos, restricciones, nulabilidad y valores por defecto. Un ALTER TABLE con múltiples declaraciones ADD COLUMN debería listar cada columna en su propia línea. El formateo hace que la revisión de migraciones sea más rápida y reduce la posibilidad de enviar una migración con tipos de columna incorrectos o restricciones faltantes.
Preguntas frecuentes
¿Qué dialectos SQL están admitidos?
El formateador admite la sintaxis SQL estándar, incluidos SELECT, JOIN, WHERE, GROUP BY y otras cláusulas comunes.
¿Modifica la lógica de mi query?
No, el formateador solo cambia los espacios en blanco y las mayúsculas. La lógica de tu query permanece exactamente igual.
