읽기 쉬운 쿼리를 위한 5가지 SQL 포맷팅 규칙

Source: Dev.to

우리는 모두 그런 경험을 해봤습니다 — 프로젝트를 인계받아 저장 프로시저를 열었는데, 거대한 SQL 벽이 한 줄로 이어져 있죠. 들여쓰기도 없고 구조도 없으며, 온통 혼돈입니다. 혹은 6개월 전 스스로 작성했는데 이제는 무슨 일을 하는지조차 알 수 없을 때도 마찬가지입니다.

수년간 전문적으로 SQL을 작성하면서 제가 실제로 읽기 쉬운 쿼리를 만들기 위해 따르는 다섯 가지 포맷팅 규칙을 소개합니다 — 팀원은 물론 미래의 저 자신에게도 도움이 됩니다.

Rule #1: One clause per line

각 주요 SQL 절을 별도의 줄에 배치합니다.

Bad

SELECT u.id, u.name, u.email, o.total FROM users u JOIN orders o ON u.id = o.user_id WHERE o.created_at > '2024-01-01' AND u.active = 1 ORDER BY o.total DESC;

Good

SELECT u.id, u.name, u.email, o.total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE o.created_at > '2024-01-01'
  AND u.active = 1
ORDER BY o.total DESC;

즉시 스캔하기 쉬워집니다. 어떤 테이블이 사용됐는지, 조인 조건은 무엇인지, 필터는 무엇인지 바로 파악할 수 있습니다.

Rule #2: Leading commas

선행 콤마(leading commas)를 사용하면 컬럼을 주석 처리하거나 추가하기가 매우 간단합니다.

SELECT
  u.id
  , u.name
  , u.email
  , u.created_at
  -- , u.phone  (쉽게 토글 가능!)
FROM users u

컬럼을 제거해야 할 때, 뒤쪽 콤마 문제에 신경 쓸 필요 없이 해당 줄을 주석 처리하면 됩니다.

Rule #3: Keep CTEs clean

CTE(WITH 절)는 강력하지만 금방 지저분해질 수 있습니다. 각 CTE를 명확하고 독립적인 블록으로 유지하세요.

WITH active_users AS (
  SELECT id, name, email
  FROM users
  WHERE active = 1
    AND last_login > '2024-06-01'
),
recent_orders AS (
  SELECT user_id, SUM(total) AS total_spent
  FROM orders
  WHERE created_at > '2024-01-01'
  GROUP BY user_id
)
SELECT
  au.name
  , au.email
  , ro.total_spent
FROM active_users au
JOIN recent_orders ro ON au.id = ro.user_id
ORDER BY ro.total_spent DESC;

Rule #4: Visual hierarchy

키워드와 절을 정렬해 명확한 시각적 계층 구조를 만듭니다.

SELECT u.name, COUNT(*) AS order_count
FROM users u
INNER JOIN orders o ON u.id = o.user_id
WHERE u.country = 'US'
GROUP BY u.name
HAVING COUNT(*) > 5
ORDER BY order_count DESC;

키워드만 눈으로 훑어도 쿼리 구조를 이해할 수 있어, 세부 내용을 모두 읽지 않아도 됩니다.

Rule #5: Use automated formatters

수동 포맷팅은 일관성이 떨어지기 쉽습니다, 특히 팀 환경에서는 더욱 그렇죠. 자동 포맷터를 사용하면 위 규칙들을 대부분 자동으로 적용할 수 있습니다.

• SQLNice – 무료 온라인 SQL 포맷터.
• 내장 IDE 포맷터(DataGrip, DBeaver).
• sql-formatter 혹은 pgFormatter 같은 CLI 도구.

Benefits of clean SQL

• 코드 리뷰 속도 – 리뷰어가 문제를 더 빨리 발견합니다.
• 디버깅 – 각 절이 별도 줄에 있으면 문제를 쉽게 격리할 수 있습니다.
• 온보딩 – 새로운 팀원이 로제타 스톤 없이도 쿼리를 읽을 수 있습니다.
• 버전 관리 – 각 요소가 별도 줄에 있어 차이점이 깔끔하게 표시됩니다.

SQL 포맷팅은 매일매일 혜택을 주는 작은 투자 중 하나입니다. 먼저 Rule #1(한 줄에 한 절)부터 시작해 점차 확장해 보세요.

여러분 팀에서는 어떤 포맷팅 규칙을 따르고 있나요? 댓글로 알려 주세요—저는 언제나 SQL 실력을 향상시킬 방법을 찾고 있습니다.