Cómo formatear consultas SQL

El SQL desordenado es una de las formas mas rapidas de introducir errores. Cuando una consulta es una sola linea larga sin sangria, es dificil ver que condiciones se aplican a que uniones, donde comienzan y terminan las subconsultas, o si la logica es correcta. Un formateador basado en navegador maneja todo el trabajo localmente sin subir sus consultas a un servidor.

Por que importa el formateo

• Depuracion: una consulta bien formateada hace visibles los errores de logica. Puede rastrear el flujo de SELECT a WHERE a JOIN sin adivinar.
• Revision de codigo: los revisores pueden leer SQL formateado en segundos. Una consulta de una sola linea los obliga a analizarla mentalmente primero.
• Mantenimiento: cuando revisa una consulta meses despues, el formateo le dice de un vistazo lo que hace.
• Colaboracion: el formateo consistente en un equipo significa que todos leen SQL de la misma manera.
• Incorporacion: los nuevos miembros del equipo pueden leer SQL formateado sin necesitar el historial oral de cada consulta.
• Documentacion: cuando SQL aparece en documentos de diseno, runbooks o wikis, las consultas formateadas son mas faciles de seguir para los no desarrolladores.
• Diferencias de control de version: el SQL formateado produce diferencias mas limpias cuando cambia una clausula sin reformatear toda la consulta.

Como formatear SQL

1. Pegue su SQL: ingrese una consulta minificada o desordenada en el formateador. Maneja SELECT, INSERT, UPDATE, DELETE, CREATE TABLE y consultas complejas con subconsultas y uniones.
2. Configure las opciones: elija el tamano de sangria y si quiere palabras clave en mayusculas. Estos ajustes coinciden con la guia de estilo de su proyecto.
3. Copie el resultado: el SQL formateado esta listo para pegar de vuelta en su editor, cliente de base de datos o documentacion.

Como se ve un buen formateo

Una consulta como select u.name, o.total from users u join orders o on u.id = o.user_id where o.total > 100 and u.active = 1 order by o.total desc se convierte en:

SELECT
  u.name,
  o.total
FROM users u
JOIN orders o
  ON u.id = o.user_id
WHERE o.total > 100
  AND u.active = 1
ORDER BY o.total DESC

Cada clausula comienza en su propia linea. Las condiciones estan sangradas bajo su clausula padre. Las uniones y sus condiciones ON estan claramente emparejadas.

Una breve historia de las convenciones de formateo SQL

SQL fue creado por los investigadores de IBM Donald Chamberlin y Raymond Boyce en 1974, originalmente llamado SEQUEL (Structured English Query Language). El «QL» en el nombre original reflejaba la intencion de que el lenguaje se leyera como ingles. Desde el principio, este diseno legible por humanos implicaba una convencion: sangre sus clausulas para que se lean de arriba abajo como oraciones.

Durante la mayor parte de los anos 1980 y 1990, el SQL se escribia a mano en editores de texto y el formateo era personal. Algunos talleres adoptaron el «estilo rio» (donde cada palabra clave se alinea verticalmente a la derecha de una columna virtual), otros usaron el «estilo egipcio» (equivalente de llave-en-la-misma-linea), y la mayoria simplemente usaron lo que el autor preferia.

El primer formateador SQL ampliamente utilizado fue Apex SQL Formatter (2000), seguido de SQL Complete de Devart (2002) y SQL Prompt de Red Gate (2003). Estas herramientas trajeron el formateo a nivel IDE a los desarrolladores de SQL Server y Oracle. Para 2010, todos los IDE principales (SSMS, DataGrip, DBeaver) tenian formateo SQL integrado, y los formateadores en linea se convirtieron en estandar para la limpieza ad hoc.

En 2017, el ecosistema de formateadores cambio con sql-formatter (npm), una biblioteca JavaScript de codigo abierto que impulsa la mayoria de los formateadores SQL basados en navegador hoy en dia, incluido este. Los formateadores modernos manejan las diferencias de dialecto (backticks de MySQL, funciones de ventana de PostgreSQL, corchetes cuadrados de SQL Server) y producen salida consistente y configurable.

Guias de estilo SQL usadas por grandes empresas

La mayoria de las bases de codigo profesionales siguen una de las varias guias de estilo SQL publicadas:

Si esta comenzando un nuevo proyecto, elija una de las guias establecidas. Si se une a una base de codigo existente, siga lo que ya hay alli. La consistencia dentro de un proyecto importa mas que cualquier estilo especifico.

Opciones de formateo comunes

• Caja de palabras clave: MAYUSCULAS (mas comun, hace las palabras clave visualmente distintivas), minusculas (estilo moderno dbt/Snowflake), o caja original (algunos IDE conservan lo que escribio).
• Caja de identificadores: snake_case es el predeterminado en PostgreSQL y la mayoria de bases de datos amigables con Unix; PascalCase o camelCase en las tradiciones de Oracle/SQL Server.
• Sangria: 2 espacios (compacto, cabe en terminal de 80 caracteres), 4 espacios (coincide con la mayoria de guias de estilo de codigo), o tabulaciones (raro en SQL).
• Colocacion de comas: comas finales (despues de cada columna en linea separada) o comas iniciales (coma al inicio de la siguiente linea, mas facil de agregar/eliminar columnas).
• Longitud de linea: 80 caracteres (amigable con terminal), 120 caracteres (predeterminado moderno de IDE), o ilimitada (menos comun en produccion).
• Estilo JOIN: palabra clave ANSI JOIN (preferida) vs viejo estilo separado por comas FROM con condiciones de union WHERE (obsoleto).
• Formateo de subconsultas: sangrar subconsultas dentro de parentesis, usar Expresiones de Tabla Comunes (CTE) para claridad, o anidar con alias explicitos.

Diferencias de dialectos

Los formateadores SQL necesitan manejar sintaxis especifica de dialectos:

Un buen formateador detecta o acepta una pista de dialecto, luego maneja sintaxis que otros dialectos rechazarian.

Errores comunes

• Reformatear dentro de scripts de produccion: cambiar espacios en blanco en un script de migracion que ya ha sido parcialmente aplicado puede causar problemas si su herramienta de migracion toma huellas digitales por hash. Formatee antes de la primera ejecucion.
• Literales de cadena reformateados: una cadena multilinea dentro de una consulta no deberia ser reformateada por el formateador SQL; algunos formateadores ingenuos rompen cadenas en linea.
• Comentarios perdidos o mal colocados: los comentarios SQL (guiones de una sola linea y slash-asterisco multilinea) necesitan sobrevivir al formateo. Algunos formateadores los abandonan o los mueven de formas confusas.
• Citas de identificador cambiadas: identificadores entre comillas dobles en PostgreSQL o entre backticks en MySQL tienen significados especificos. Un formateador que «normaliza» quitando comillas puede cambiar el comportamiento de la consulta si el identificador necesitaba comillas (palabra reservada, caso mixto en PostgreSQL).
• Funciones de ventana mal formateadas: OVER (PARTITION BY x ORDER BY y) debe mantenerse legible. El ajuste de linea agresivo dentro de parentesis de funcion de ventana produce salida desordenada.
• Cadenas CTE sobre-sangradas: WITH cte1 AS (...), cte2 AS (...) puede anidarse demasiado profundo por algunos formateadores. La mayoria de formateadores modernos mantienen los CTE al nivel superior.
• Cadenas entre dolares (funciones PostgreSQL): los cuerpos de funcion envueltos en $$ no deberian tener su contenido reformateado. Algunos formateadores los destrozan.
• Palabras clave especificas del proveedor mal clasificadas: un formateador que no conoce QUALIFY (Snowflake) o LATERAL (PostgreSQL) puede no capitalizarlas o alinearlas correctamente.
• Procedimientos almacenados con flujo de control: los bloques BEGIN/END, IF/THEN/ELSE en T-SQL o PL/SQL necesitan reglas de sangria diferentes a las consultas puras.

Consejos

• Formatee antes de hacer commit: pase su SQL por un formateador antes de agregarlo al control de version. Esto mantiene las diferencias limpias y las revisiones enfocadas en la logica, no en el estilo.
• Use casos de palabras clave consistentes: elija palabras clave en mayusculas o minusculas y quedese con eso en todo su proyecto. Mezclar estilos hace las consultas mas dificiles de leer.
• Desglose consultas complejas: si una consulta aun es dificil de leer despues del formateo, considere desglosarla en CTE (Expresiones de Tabla Comunes) o vistas. El formateo no puede arreglar logica fundamentalmente compleja.
• Verifique el resaltado de sintaxis: un buen formateador proporciona resaltado codificado por colores que hace las palabras clave, cadenas y numeros visualmente distintivos, lo que ayuda a atrapar errores tipograficos.
• Formatee solo lo que cambia: en una base de codigo grande existente, reformatear todo a la vez produce una diferencia enorme que oscurece los cambios reales. Formatee incrementalmente mientras toca las consultas.
• Configure su editor: VS Code (SQLTools, vscode-sql-formatter), DataGrip, DBeaver y pgAdmin todos tienen formateadores integrados o basados en extensiones. Configure una vez y olvidese.
• Cuidado con bases de datos sensibles al caso: PostgreSQL es sensible al caso para identificadores entre comillas. Un formateador que cambia el caso de identificadores entre comillas romperia las consultas.
• Pruebe la consulta formateada: despues de reformatear, ejecute la consulta para verificar que la salida no haya cambiado. La mayoria de los formateadores son confiables, pero un error en el formateador puede corromper una consulta.
• Use CTE sobre subconsultas anidadas: una cadena CTE es casi siempre mas facil de leer y depurar que la subconsulta anidada equivalente, incluso despues del formateo.

Privacidad y consultas confidenciales

El formateador SQL se ejecuta completamente en su navegador. Las consultas que pega, el procesamiento intermedio y la salida formateada se quedan todos en su dispositivo. Nada se sube a un servidor, se registra o se comparte con nadie.

Esto importa porque las consultas SQL a menudo contienen informacion extremadamente sensible: nombres de tablas que revelan la arquitectura del producto, nombres de columnas que exponen la logica de negocio y metricas, IDs reales de clientes en clausulas WHERE, endpoints de API internos en procedimientos almacenados, SSN y numeros de tarjeta de credito en datos de prueba, compensacion de empleados en consultas de RRHH, cifras financieras en consultas de analitica, direcciones de correo electronico de clientes en consultas de marketing. Los formateadores SQL en la nube registran cada consulta en sus registros de solicitud, a veces las retienen para «mejora del servicio», y han estado involucrados en brechas reales donde consultas de produccion pegadas filtraron esquemas y datos sensibles. Un formateador basado en navegador tiene exposicion cero: la consulta nunca sale de su maquina.

El formateo basado en navegador tambien funciona sin conexion una vez cargada la pagina, util para formatear consultas en aviones, en entornos seguros sin acceso a internet, o en cualquier lugar donde no pueda o no deba pegar una consulta de base de datos en un servicio de terceros.