Форматирование SQL-запросов _

Как работает форматирование SQL

Форматирование SQL — это лексически управляемая перезапись, при которой каждый токен запроса обходится и вокруг него заново расставляются пробелы по правилам выбранного диалекта. Семантика запроса не меняется — изменяется только его оформление.

1. Выберите диалект. Обратные кавычки MySQL, касты :: в PostgreSQL, точечные пути к таблицам BigQuery и квадратные скобки T-SQL требуют токенайзера, который их понимает. Селектор диалекта выбирает нужную грамматику.
2. Токенизация входных данных. Форматировщик разбивает запрос на поток токенов: ключевые слова (SELECT, JOIN), идентификаторы, литералы, операторы, скобки и комментарии. Строковые литералы и идентификаторы в кавычках передаются без изменений, сохраняя диалектно-специфичный синтаксис.
3. Применение правил оформления. Клаузы верхнего уровня (SELECT, FROM, WHERE, GROUP BY, ORDER BY) начинаются на новой строке. Выражения, разделённые запятыми в списке выборки и списках столбцов, получают каждое свою строку с отступом.
4. Применение регистра ключевых слов. Переключатель регистра перезаписывает распознанные ключевые слова SQL в верхний, нижний регистр или сохраняет исходный регистр. Идентификаторы не затрагиваются — имена столбцов и таблиц всегда выводятся как написаны.
5. Вывод отформатированной строки. Поток токенов снова объединяется в строку с символом отступа (2 пробела, 4 пробела или табуляция) и настроенным правилом переноса. В режиме реального времени весь конвейер перезапускается с задержкой 200 мс по мере ввода.

Зачем форматировать SQL

• Читаемость diff в pull-request'е. 200-строчный CTE, переписанный в одну строку, превращает код-ревью в угадайку. Единообразное форматирование ограничивает diff реальным изменением — новым столбцом, лишним JOIN, другим предикатом WHERE — и ревьюер видит его без разбора пробелов.
• Упрощение отладки. Когда запрос возвращает неверное число строк, первым делом его читают построчно. Отформатированный SQL размещает каждый JOIN на отдельной строке и выравнивает предикаты WHERE, так что пропущенный AND или лишний OR виден с первого взгляда.
• Единый стиль команды. Большинство команд принимают гайд по стилю SQL (dbt Labs, GitLab, Mode Analytics публикуют свои) и хотят, чтобы каждый зафиксированный запрос ему следовал. Прогон форматировщика перед коммитом убирает стилистические споры из ревью и оставляет только логику для обсуждения.
• Публикация SQL в документации. Рунбуки, ретроспективы инцидентов и документы Notion выигрывают от SQL, который читается сверху вниз. Отформатированный SQL чисто вставляется в блок кода с ограждением и предсказуемо печатается в PDF без переносов посреди ключевого слова.

Типичные сценарии применения

SQL-форматирование встречается в аналитической инженерии, бэкенд-разработке и операционной работе всякий раз, когда запрос должен прочитать тот, кто его не писал.

• Аналитическая инженерия: pre-commit хук в dbt-проекте, который переформатирует каждый файл модели, чтобы diff в PR ограничивался логическими изменениями, а не пробельным шумом.
• Администрирование баз данных: вставьте однострочную запись из slow-query log, отформатируйте её и разберите порядок соединений при написании postmortem.
• Документация: возьмите запрос из Looker Explore или Tableau-воркбука, отформатируйте для рунбука и вставьте как готовый к копированию пример для дежурной смены.

Разобранный пример

Вставьте SELECT u.id,u.email,COUNT(o.id) FROM users u LEFT JOIN orders o ON o.user_id=u.id WHERE u.created_at > '2024-01-01' GROUP BY u.id,u.email ORDER BY u.id; в панель ввода, выберите диалект PostgreSQL, отступ 2 пробела и регистр ключевых слов ВЕРХНИЙ. Результат поместит SELECT, FROM, LEFT JOIN, WHERE, GROUP BY и ORDER BY каждый на своей строке; каждый столбец в списке выборки и group-by получит свою строку с отступом; предикат ON будет на один отступ глубже ключевого слова JOIN.

FAQ

Какие диалекты SQL поддерживаются?

Выпадающий список диалектов охватывает Standard SQL, MySQL, PostgreSQL, SQLite, MariaDB, Transact-SQL (SQL Server / Azure SQL), BigQuery, Snowflake и Redshift. Базовая библиотека sql-formatter также распознаёт DuckDB, Spark SQL, Hive, Trino, Db2, N1QL, PL/SQL, ClickHouse, TiDB и SingleStoreDB — выбор ближайшего диалекта даёт осмысленный результат, даже если точная цель не в списке. Идентификаторы, строковые литералы и диалектно-специфичные операторы (PostgreSQL @>, префиксы BigQuery SAFE.) сохраняются дословно.

Проверяет ли инструмент мой SQL?

Нет. Форматировщик — это лексический перезаписчик, а не парсер. Он токенизирует входные данные, применяет правила оформления и выдаёт результат; он не проверяет семантическую корректность запроса, существование таблиц или законность синтаксиса в выбранном диалекте. Для реальной проверки корректности прогоните отформатированный результат через базу данных или SQL-линтер (например, SQLFluff).

Почему мои ключевые слова переводятся в верхний регистр?

Выпадающий список регистра по умолчанию установлен в ВЕРХНИЙ — это соглашение большинства опубликованных SQL-гайдов (dbt Labs, Mode, GitLab). Переключитесь на нижний, если ваша команда пишет select / from строчными буквами, или на Сохранить, чтобы вывод сохранял ваш исходный регистр. Идентификаторы никогда не затрагиваются.

Мой запрос куда-то загружается?

Нет. Встроенная библиотека sql-formatter работает в вашем браузере, форматирование происходит локально на вашем устройстве, и текст запроса не пересекает сеть. Единственные исходящие запросы этой страницы — это те же общие запросы аналитики и рекламы, что и у каждой страницы на tools.ultim8soft.com; текст SQL не является частью ни одного из них.

Красиво напечатанный SQL перестаёт быть поводом для споров о стиле, как только форматирование отдано инструменту. Всё работает в вашем браузере, запрос не покидает страницу, а перезапись выполняет тот же диалектно-осведомлённый токенайзер, что и npm-пакет sql-formatter.