SQL Formatter: Make Queries Readable

나는 여전히 3년 전 회사에서 떠난 개발자로부터 15,000줄의 저장 프로시저를 상속받았던 날을 기억한다. 주석도 없고, 포맷도 없었다. 마치 누군가 알파벳 수프를 텍스트 편집기에 쏟아부은 것 같은 SQL의 벽이었다. 이 파일 하나로 우리 팀은 47시간의 디버깅 시간을 소비했으며, 중요한 제품 출시가 거의 무산될 뻔했다. 그때 나는 읽기 쉬운 SQL이 사치가 아니라 비즈니스 필요라는 것을 배웠다.

저는 마커스 첸이며, 지난 12년간 중형 SaaS 회사에서 데이터베이스 아키텍트로 일했습니다. 그 동안 다양한 스킬 수준의 개발자들이 작성한 10,000개 이상의 SQL 쿼리를 검토했습니다. 뛰어난 엔지니어들이 이해할 수 없는 쿼리를 작성하는 모습을 보았고, 주니어 개발자들이 아름답게 포맷된 코드를 만드는 것도 보았습니다. 그 차이는 무엇일까요? 후자 그룹은 SQL이 작성되는 것보다 읽히는 빈도가 훨씬 더 높다는 근본적인 사실을 이해했습니다. 제 경험에 따르면, 잘 포맷된 쿼리는 디버깅 시간을 60-70% 줄이고 새로운 팀원들의 온보딩 시간을 거의 절반으로 줄입니다.

오늘은 SQL 포맷팅에 대해 제가 배운 것, 즉 스타일 가이드에서 찾을 수 있는 학문적 규칙이 아니라 기한이 촉박하고 기술 부채가 현실인 프로덕션 환경에서 실제로 효과가 있는 실용적인 접근 방식을 공유하고자 합니다.

SQL 포맷팅이 실제로 중요한 이유 (미적 목적을 넘어서)

솔직히 말하자면: 대부분의 개발자들은 SQL 포맷팅이 코드를 "예쁘게" 만드는 것이라고 생각합니다. 그들은 잘못 알고 있습니다. 포맷팅은 인지 부담, 디버깅 효율성 및 팀 속도에 관한 것입니다. 제가 코드 리뷰를 진행할 때, 형식이 좋지 않은 쿼리를 몇 초 안에 찾아낼 수 있으며, 해당 쿼리에 성능 문제나 논리 오류가 있을 것인지 약 85%의 정확도로 예측할 수 있습니다.

그 이유는 이렇습니다: 인간의 뇌는 의미론적 의미를 처리하기 전에 시각적 패턴을 처리합니다. 잘 포맷된 쿼리를 보면, 뇌는 곧바로 구조를 이해합니다—SELECT 절, JOIN, WHERE 조건 및 그룹화 논리. 10-15초 안에 스캔하며 그 쿼리가 무엇을 하는지 이해할 수 있습니다. 반면 포맷되지 않은 쿼리는 모든 단어를 순차적으로 해석해야 하므로 3-5배 더 오래 걸리며, 오해의 기회가 훨씬 더 많아집니다.

작년 제 팀과 함께 비공식 실험을 진행했습니다. 10개의 쿼리를 디버깅하게 했는데—5개는 포맷된 쿼리, 5개는 포맷되지 않은 쿼리였습니다. 포맷된 쿼리는 평균 8.3분이 걸렸습니다. 포맷되지 않은 것은? 23.7분이 걸렸습니다. 이는 작은 차이가 아닙니다. 수백 개의 쿼리와 수십 명의 개발자를 놓고 계산하면, 연간 수천 시간을 낭비하는 생산성을 초래합니다.

하지만 그 영향은 시간에 그치지 않습니다. 형식이 좋지 않은 SQL은 실제 버그로 이어집니다. 저는 개발자들이 300자 단일 줄에 묻혀 있는 중요한 WHERE 절 조건을 놓치는 것을 보았습니다. 팀이 관계가 시각적으로 명확하지 않아서 잘못된 JOIN 논리로 쿼리를 배포하는 것도 보았습니다. 잊지 못할 한 경우에는, 형식이 좋지 않은 쿼리가 47,000명의 고객 기록에 영향을 미친 데이터 무결성 문제를 일으켰습니다. 누군가 서브쿼리가 상관 조건을 빠뜨렸다는 것을 보지 못했기 때문입니다.

재정적 영향도 실제입니다. 이전 회사에서 우리는 SQL 가독성이 좋지 않아 연간 약 180,000달러의 비용이 발생하고 있다는 계산을 했습니다. 이는 개발자 시간, 버그 수정 및 성능 최적화 작업에 기인합니다. 포맷팅 기준 및 도구를 구현한 후, 우리는 그 비용을 6개월 이내에 약 65% 줄일 수 있었습니다.

잘 포맷된 쿼리의 구조

도구에 대해 이야기하기 전에, 좋은 포맷팅이 실제로 어떤 모습인지 정립해 보겠습니다. 저는 수년 동안 제가 작성하거나 검토하는 모든 쿼리에서 적용할 수 있는 정신적인 체크리스트를 개발했습니다. 이는 임의의 규칙을 따르는 것이 아니라, 논리 구조에 매핑되는 시각적 구조를 만드는 것입니다.

첫째, 키워드는 각기 다른 줄에 있거나 명확하게 구분되어야 합니다. SELECT, FROM, WHERE, GROUP BY 및 ORDER BY가 각각 새 줄에서 시작할 때, 저는 즉시 쿼리의 뼈대를 이해할 수 있습니다. 이는 여러 CTE나 서브쿼리가 있는 복잡한 쿼리에서는 특히 중요합니다. 이런 식으로 포맷된 쿼리는 코드 리뷰 중 이해하는 데 약 40% 더 빨라졌습니다.

둘째, 들여쓰기는 논리적 계층 구조를 반영해야 합니다. 서브쿼리가 있는 경우, 부모에 대해 들여쓰기가 되어야 합니다. 여러 JOIN 조건이 있는 경우, 수직으로 정렬되어야 합니다. 이 시각적 계층 구조는 관계를 한눈에 이해할 수 있게 해줍니다. 저는 일반적으로 각 들여쓰기 수준에 대해 4개의 공백을 사용하지만, 더 компакт한 코드를 선호하는 팀에게는 2개의 공백도 괜찮습니다.

셋째, 긴 경우 열 목록은 수직으로 정렬되어야 합니다. 15개의 열을 선택하고 모든 것을 한 줄에 두는 것은 미친 짓입니다. 그것들을 한 줄에 하나씩 나누고, 쉼표를 앞에 두는 것이 좋습니다 (네, 저는 앞 쉼표 캠프에 속하며, 그 선택을 방어하겠습니다). 이렇게 하면 열을 추가, 제거 또는 재정렬하는 것이 간단해지며 코드의 diff를 읽기가 훨씬 수월해집니다.

구체적인 예를 들어보겠습니다. 다음은 제가 생산 환경에서 자주 보는 쿼리입니다:

형식이 없는 버전:

SELECT u.user_id,u.email,u.created_at,o.order_id,o.total_amount,o.order_date FROM users u INNER JOIN orders o ON u.user_id=o.user_id WHERE u.status='active' AND o.order_date>=DATEADD(day,-30,GETDATE()) AND o.total_amount>100 GROUP BY u.user_id,u.email,u.created_at,o.order_id,o.total_amount,o.order_date HAVING COUNT(*)>1 ORDER BY o.order_date DESC;

이제 제가 포맷하는 방법은 다음과 같습니다:

SELECT
    u.user_id
    , u.email
    , u.created_at
    , o.order_id
    , o.total_amount
    , o.order_date
FROM users u
INNER JOIN orders o
    ON u.user_id = o.user_id
WHERE u.status = 'active'
    AND o.order_date >= DATEADD(day, -30, GETDATE())
    AND o.total_amount > 100
GROUP BY
    u.user_id
    , u.email
    , u.created_at
    , o.order_id
    , o.total_amount
    , o.order_date
HAVING COUNT(*) > 1
ORDER BY o.order.date DESC;

차이는 하늘과 땅 차이입니다. 포맷된 버전에서는 사용자를 주문에 join하고, 최근의 고가치 주문을 가진 활성 사용자에게 필터링하고, 중복을 찾고 있다는 것을 즉시 알 수 있습니다. 포맷되지 않은 버전은 동일한 정보를 추출하기 위해 careful reading이 필요합니다.

올바른 SQL 포맷터 도구 선택하기

수동 포맷팅은 작은 쿼리에는 괜찮지만, 프로덕션 환경에서는 자동화가 필요합니다. 저는 수년 동안 약 20개의 SQL 포맷팅 도구를 평가했으며, "최고"의 도구는 특정 맥락—데이터베이스 플랫폼, 개발 워크플로우 및 팀의 선호도—에 크게 의존한다는 것을 배웠습니다.

온라인 포맷터의 경우, SQLFormat.org 및 Instant SQL Formatter와 같은 도구들이 빠른 포맷 작업에 잘 작동한다는 것을 알게 되었습니다. 이들은 무료이며, 설치할 필요가 없고, 대부분의 SQL 방언을 상당히 잘 처리합니다. 누군가 슬랙이나 이메일로 보낸 쿼리를 빠르게 포맷해야 할 때, 저는 아마 주 3-4회 SQLFormat.org를 사용합니다. 주요 제한 사항은 잠재적으로 민감한 쿼리를 제3자 웹사이트에 붙여넣는 것이므로, 대부분의 조직에서 프로덕션 코드에는 사용할 수 없습니다.

IDE 통합의 경우, 저는 VS Code, IntelliJ 및 DataGrip을 위한 SQL 포맷팅 플러그인에 큰 팬입니다. 이러한 도구들은 여러분이 입력하는 대로 포맷하거나 컴퓨터에서 자동으로 포맷...