SQL Formatter: Make Queries Readable

私はまだ、3年前に会社を去った開発者から15,000行のストアドプロシージャを引き継いだ日のことを覚えています。コメントはなし。フォーマットもなし。ただ、テキストエディタにアルファベットスープを投げ込んだように見えるSQLの壁。あの1つのファイルは、私たちのチームに47時間のデバッグ時間を要し、重要な製品のローンチを寸前で derail させるところでした。そのとき私は、読みやすいSQLは贅沢ではなく、ビジネスの必須条件であることを学びました。

私はマーカス・チェンで、中規模SaaS企業でのデータベースアーキテクトとして過去12年間を過ごしてきました。その間、私は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ロジックでクエリを展開するチームを見ました。ある記憶に残るケースでは、フォーマットされていないクエリがデータ整合性の問題を引き起こし、4万7000件の顧客記録に影響を与えました。これは、誰かがサブクエリに相関条件が欠けていることを見られなかったためです。

財務的影響も実際にあります。前の会社では、悪いSQLの可読性が開発者の時間、バグ修正、パフォーマンス最適化作業で年間約18万ドルのコストをかけていることを計算しました。フォーマット基準とツールを実装した後、6ヶ月以内にそのコストを約65％削減しました。

よくフォーマットされたクエリの構造

ツールについて話す前に、良いフォーマットが実際にどのようなものかを明確にしましょう。私は、書くかレビューするすべてのクエリに適用するメンタルチェックリストを何年もかけて開発してきました。これは恣意的なルールを守ることではなく、論理構造に対応する視覚的構造を作り出すことに関するものです。

まず、キーワードはそれぞれ独立した行に配置するか、明確に分けるべきです。SELECT、FROM、WHERE、GROUP BY、ORDER BY がそれぞれ新しい行から始まるのを見ると、すぐにクエリの構造を理解できます。これは、複数のCTEやサブクエリのある複雑なクエリにとって特に重要です。この方法でフォーマットされたクエリは、コードレビュー中の理解が約40％速くなります。

次に、インデントは論理的な階層を反映する必要があります。サブクエリがある場合、それは親に対してインデントされるべきです。複数のJOIN条件がある場合、それらは垂直に整列すべきです。この視覚的な階層により、一目で関係を理解できます。私は通常、各インデントレベルに4スペースを使用しますが、よりコンパクトなコードを好むチームには2スペースも問題ありません。

第三に、列リストは長い場合、垂直に整列する必要があります。15列を選択する場合、すべてを1行に配置するのは狂気です。すべてを1行ずつ、カンマを前にして分けます（はい、私は前カンマ派で、この選択を擁護します）。これにより、列を追加、削除、または並べ替えるのが簡単になり、コードの差分がはるかに読みやすくなります。

具体的な例をご紹介します。これは、私がプロダクションで頻繁に見るタイプのクエリです：

フォーマットされていないバージョン：

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;

その違いは天と地です。フォーマットされたバージョンでは、私たちがユーザーを注文に結びつけていること、最近の高価値の注文を持つ活動中のユーザーをフィルタリングしていること、重複を探していることが瞬時にわかります。フォーマットされていないバージョンでは、同じ情報を抽出するために注意深く読む必要があります。

適切なSQLフォーマッターツールの選び方

手動フォーマットは小さなクエリには問題ありませんが、プロダクション環境では自動化が必要です。私はこれまでにおそらく20種類の異なるSQLフォーマッティングツールを評価してきましたが、「最良」のツールはあなたの特定の文脈—データベースプラットフォーム、開発ワークフロー、チームの好み—に大きく依存することを学びました。

オンラインフォーマッタについては、SQLFormat.org や Instant SQL Formatter のようなツールが、迅速なフォーマット作業に適していることがわかりました。これらは無料で、インストールも不要で、ほとんどのSQL方言をそれなりにサポートしています。私は大体週に3〜4回、Slackやメールで誰かから送られたクエリを迅速にフォーマットする必要があるときにSQLFormat.orgを使用しています。主な制限は、潜在的に機密性の高いクエリをサードパーティのウェブサイトに貼り付けることになり、ほとんどの組織ではプロダクションコードには不可であるという点です。

IDE統合については、VS Code、IntelliJ、DataGrip向けのSQLフォーマッティングプラグインが大好きです。これらのツールは、タイピング中またはコマンドに応じてフォーマットします。