SQL 포매터 — MySQL, PostgreSQL, BigQuery 온라인

쿠팡 데이터 엔지니어링 팀은 Snowflake 위에서 dbt를 운영하며, 모든 모델 파일을 pre-commit 훅으로 포매팅하여 PR diff가 로직 변경만 보여주도록 합니다. 200줄짜리 CTE를 한 줄로 붙여넣으면 diff가 공백 노이즈로 폭발해 실제 JOIN 변경을 가립니다. 카카오 BigQuery 코드 리뷰에서도 키워드 대소문자 불일치는 반복 지적 사항입니다. 토스 Trino 클러스터와 Athena 쿼리도 공통 스타일 가이드를 따르며, 이 툴이 dialect-aware tokenizer로 그 규칙을 자동 적용합니다. PIPA 규정상 고객 식별자가 담긴 쿼리를 외부 서버에 올릴 수 없으므로, 브라우저 안에서만 동작하는 이 포매터가 적합합니다.

SQL 포매팅 작동 원리

SQL 포매팅은 렉서 기반 재작성으로, 쿼리의 모든 토큰을 순회하며 선택한 방언의 규칙에 따라 공백을 재출력합니다. 쿼리 의미는 변하지 않고 레이아웃만 바뀝니다.

방언 선택. MySQL 백틱, PostgreSQL :: 캐스트, BigQuery 점 경로 테이블, T-SQL 대괄호 식별자는 각각 이를 인식하는 토크나이저가 필요합니다. 방언 선택기가 적용할 문법을 결정합니다.
입력 토큰화. 포매터는 쿼리를 토큰 스트림으로 분리합니다: 키워드(SELECT, JOIN), 식별자, 리터럴, 연산자, 괄호, 주석. 문자열 리터럴과 따옴표 식별자는 그대로 통과하여 방언 특정 구문이 유지됩니다.
레이아웃 규칙 적용. 최상위 절(SELECT, FROM, WHERE, GROUP BY, ORDER BY)은 각자 새 줄에서 시작합니다. 선택 목록과 컬럼 목록의 쉼표 구분 표현식은 각각 한 줄씩 선택한 들여쓰기 단위로 들여씁니다.
키워드 대소문자 적용. 키워드 대소문자 토글은 인식된 SQL 키워드를 대문자, 소문자로 재작성하거나 입력 그대로 유지합니다. 식별자는 절대 변경되지 않습니다 — 컬럼명과 테이블명은 항상 원본 그대로 출력됩니다.
포맷된 문자열 출력. 토큰 스트림은 들여쓰기 문자(공백 2칸, 4칸 또는 탭)와 설정된 줄바꿈 규칙으로 하나의 문자열로 합쳐집니다. 실시간 모드는 입력 중 200ms 디바운스로 전체 파이프라인을 재실행합니다.

SQL을 보기 좋게 출력하는 이유

Pull request diff 가독성. 200줄짜리 CTE를 한 줄로 재작성하면 코드 리뷰가 추측 게임이 됩니다. 일관된 포매팅은 diff를 실제 변경 — 새 컬럼, 추가 JOIN, 다른 WHERE 조건 — 에만 국한시켜 리뷰어가 공백 없이 볼 수 있게 합니다.
디버깅 용이성. 쿼리가 잘못된 행 수를 반환하면 먼저 줄 단위로 읽게 됩니다. 포맷된 SQL은 각 JOIN을 독립 줄에 배치하고 WHERE 조건을 정렬하여 빠진 AND나 잘못된 OR가 한눈에 보입니다.
팀 스타일 일관성. 대부분의 팀은 SQL 스타일 가이드를 채택하고(dbt Labs, GitLab, Mode Analytics 모두 발행) 커밋된 쿼리가 이를 따르기를 원합니다. 커밋 전 포매터 실행으로 리뷰에서 스타일 논쟁을 제거하고 로직만 논의하게 됩니다.
문서에서 SQL 공유. 런북, 장애 리트로, Notion 문서 모두 위에서 아래로 읽히는 SQL에서 이점을 얻습니다. 포맷된 SQL은 코드 블록에 깔끔하게 붙여넣어지고 PDF 내보내기에서 키워드 중간 줄바꿈 없이 예측 가능하게 출력됩니다.

일반적인 활용 사례

SQL 포매팅은 분석 엔지니어링, 백엔드 개발, 운영 작업에서 쿼리를 작성하지 않은 사람이 읽어야 할 때마다 등장합니다.

분석 엔지니어링: dbt 프로젝트의 pre-commit 훅으로 모든 모델 파일을 재포매팅하여 PR diff가 로직 변경에만 집중되고 공백 변화가 없도록 합니다.
데이터베이스 관리: slow-query 로그의 한 줄 항목을 붙여넣고 포맷한 후 장애 보고서를 작성하면서 조인 순서를 분석합니다.
문서화: 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 방언을 지원하나요?

방언 드롭다운에는 표준 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을 검증하나요?

아니요. 포매터는 어휘 재작성기이지 파서가 아닙니다. 입력을 토큰화하고 레이아웃 규칙을 적용해 결과를 출력할 뿐, 쿼리가 의미적으로 유효한지, 참조된 테이블이 존재하는지, 선택한 방언에서 구문이 합법적인지는 확인하지 않습니다. 실제 정확성 검사는 실제 데이터베이스(또는 SQLFluff 같은 SQL 린터)를 사용하세요.

키워드가 왜 대문자로 변환되나요?

키워드 대소문자 드롭다운 기본값은 대문자로, 대부분의 SQL 스타일 가이드(dbt Labs, Mode, GitLab)의 관례입니다. 팀이 소문자 select / from을 사용한다면 소문자로 전환하고, 입력 대소문자를 유지하려면 유지를 선택하세요. 식별자는 절대 영향받지 않습니다.

쿼리가 어딘가에 업로드되나요?

아니요. 번들된 sql-formatter 라이브러리가 브라우저에서 실행되고, 포매팅은 로컬 머신에서 이루어지며, 쿼리 텍스트는 네트워크를 통하지 않습니다. 이 페이지의 유일한 외부 요청은 tools.ultim8soft.com의 모든 페이지가 공통으로 보내는 분석·광고 요청이며, SQL 텍스트는 그 어느 것의 일부도 아닙니다.

보기 좋게 출력된 SQL은 포매터가 처리하면 더 이상 스타일 논쟁이 아닙니다. 이 툴은 완전히 브라우저에서 실행되며 쿼리는 페이지를 벗어나지 않고, sql-formatter npm 패키지를 구동하는 동일한 방언 인식 토크나이저가 재작성을 수행합니다.

SQL 쿼리 포매팅 _

// 관련 도구