SQL 포맷팅 모범 사례: 엔지니어를 위한 실용 가이드

Source: Dev.to
SQL은 소프트웨어 엔지니어링에서 가장 널리 사용되는 언어라고 할 수 있지만, 가장 부주의하게 작성되는 경우가 많습니다. 대부분의 팀은 애플리케이션 코드에 엄격한 린팅을 적용하지만, SQL 쿼리는 자유롭게 방치합니다. 이 가이드는 유지보수가 쉽고 팀 친화적인 SQL과, 온콜 순환을 괴롭히는 쿼리 스파게티를 구분하는 포맷팅 규칙을 다룹니다.

포맷이 맞지 않은 SQL은 단순히 미관상의 문제가 아니라 정확성 위험입니다. 밀집된 장황한 쿼리는 실수로 발생한 카르테시안 곱, 누락된 GROUP BY 절, 혹은 인덱스를 무시하는 WHERE 조건을 찾아내기 거의 불가능하게 만듭니다. 성능 문제가 프로덕션에서 드러날 때, 원인까지 추적하는 일은 다른 사람의 생각 흐름을 읽는 고통스러운 작업이 됩니다.

SQL 엔진은 select와 SELECT를 동일하게 처리하지만, 인간 독자는 그렇지 않습니다. SELECT, FROM, WHERE, JOIN, GROUP BY, ORDER BY와 같은 예약어는 항상 대문자로 표기하세요. 테이블명, 컬럼명, 별칭은 소문자로 유지합니다. 이 한 가지 습관만으로도 쿼리 로직 구조와 실제 데이터 사이에 시각적인 경계가 생깁니다.

SQL 절을 데이터 파이프라인의 레이어로 생각하세요. 주요 절—SELECT, FROM, WHERE, GROUP BY, ORDER BY—은 모두 왼쪽 여백에서 시작합니다. 그 아래에 위치하는 컬럼명과 필터 조건은 4칸(또는 1탭)씩 들여쓰기 합니다(팀 내에서 일관되게). 이렇게 하면 리뷰어가 쿼리를 위에서 아래로 훑어볼 때 데이터 흐름을 한눈에 파악할 수 있습니다.

이 주제는 데이터 팀 사이에서 실제로 논쟁이 됩니다. 각 라인의 앞에 콤마를 두는(leading commas) 방식은 컬럼을 추가·삭제할 때 버전 관리 차이를 훨씬 깔끔하게 만들어 줍니다. 반면, 라인 끝에 콤마를 두는(trailing commas) 방식은 JavaScript나 Python 배경을 가진 개발자에게 더 자연스럽게 느껴집니다. 어느 쪽이든 틀린 것은 아니지만, 같은 코드베이스 안에서 두 스타일을 섞는 것은 잘못된 것입니다. 하나의 컨벤션을 정하고 CI 파이프라인에 린터를 적용해 강제하세요.

각 JOIN은 별도의 라인에 두고, 조인 조건은 그 아래에 들여쓰기합니다. JOIN에 조건이 여러 개라면 각 조건을 별도 라인에 배치하세요. WHERE 절에서는 AND와 OR을 혼합할 때 반드시 명시적인 괄호를 사용합니다. 암시적인 연산자 우선순위에 의존하지 말고, 뒤따르는 모든 사람이 수학적으로 모호함 없이 그룹핑을 이해하도록 하세요.

SQL 가독성에 가장 큰 영향을 주는 습관 변화는 중첩 서브쿼리를 WITH 절을 이용한 공통 테이블 표현식(CTE)으로 바꾸는 것입니다. 중첩 서브쿼리는 안쪽부터 밖쪽으로 읽어야 하므로 이해하기 어렵습니다. CTE는 파이프라인의 각 단계를 이름 붙여서 위에서 아래로 쌓아 놓을 수 있게 해 주며, 데이터베이스가 실행하는 흐름과 동일한 방향으로 읽을 수 있게 합니다. 또한 개별 단계별로 독립적인 테스트가 가능해집니다.

일관된 포맷팅은 코드 가독성을 넘어 성능 버그를 시각적으로 포착하는 데 도움을 줍니다. SARGable 쿼리는 데이터베이스 엔진이 B‑Tree 인덱스를 효과적으로 활용할 수 있는 쿼리를 말합니다. 가장 흔한 실수는 인덱스가 걸린 컬럼을 함수 호출로 감싸는 것(예: UPPER(email) = 'VALUE')이며, 이는 전체 테이블 스캔을 유발합니다. 마찬가지로 WHERE 조건의 좌측에 산술 연산을 수행하면(예: created_at + INTERVAL '7 days' > NOW()) 인덱스 탐색이 무력화됩니다. 변환 작업은 모두 식의 오른쪽으로 옮겨 인덱스 사용을 유지하세요.

깨끗한 CTE를 작성하기 전에, 스프레드시트, API 응답, JSON 페이로드 등에서 대량 데이터를 다루어야 할 때가 많습니다. 이러한 소스를 수동으로 INSERT 문으로 변환하면 느리고 오류가 발생하기 쉽습니다. CSV‑to‑SQL 이나 JSON‑to‑SQL 생성기와 같은 도구는 데이터 속성을 바로 다중 행 트랜잭션 쿼리로 매핑해 주어 큰 시간을 절약해 줍니다. 반대로 쿼리 결과를 프론트엔드 팀에 빠르게 전달해야 할 경우, SQL‑to‑JSON 컨버터를 사용하면 손코딩 없이도 바로 연결할 수 있습니다.

SQL 마이그레이션이나 쿼리가 프로덕션에 배포되기 전에 반드시 확인할 항목

• 예약어는 UPPERCASE
• 중첩 서브쿼리는 CTE로 리팩터링
  - JOIN 조건은 들여쓰기하고 명시적으로 나열
  - WHERE 조건은 식의 오른쪽에서 수학 연산 수행
• 윈도우 함수는 가독성을 위해 여러 라인에 걸쳐 작성
• 모든 혼합 AND/OR 조건에 괄호를 명시적으로 사용

좋은 SQL 포맷팅은 다음에 코드를 읽고 유지보수할 엔지니어에 대한 일종의 존중입니다. CI 체크, pre‑commit 훅, 혹은 공유 SQL 린터를 통해 일관된 스타일을 강제하면 코드 리뷰에서 스타일 논쟁을 없앨 수 있고, 팀은 정확성과 성능에만 집중할 수 있습니다. 수동 포맷팅을 건너뛰고 싶다면, 온라인 SQL 포맷터를 이용해 들여쓰기, 대소문자, 콤마 위치를 즉시 표준화한 뒤 커밋하면 됩니다.

DevToolLab SQL Formatter Tool
DevToolLab CSV to SQL Tool
DevToolLab JSON to SQL Tool