02.SQL コーディング規約
このドキュメントでは、SQL（Structured Query Language）を記述する際のスタイルと規約を定めます。可読性と保守性の高いクエリ記述を目指します。
Note
"共通原則との関係" 本規約は、01.共通コーディング原則の思想を、SQLに特化・具体化したものです。必ず共通原則にも目を通してください。
1. 基本方針 (Guiding Principles)
- キーワードは常に大文字:
SELECT,FROM,WHERE,GROUP BY,JOINなどのSQL予約語は、必ず大文字で記述します。
- データ型も大文字:
VARCHAR,INTEGER,TIMESTAMPなどのデータ型も大文字で記述します。
- 関数名も大文字:
COUNT(),SUM(),NOW()などの組み込み関数名も大文字で記述します。
なぜ大文字か？
SQLの予約語や関数を大文字に統一することで、テーブル名やカラム名といった、私たちが定義した「識別子」との区別が明確になり、クエリの構造が格段に読みやすくなります。
2. レイアウトと書式設定 (Layout and Formatting)
手作業でのスタイル遵守は非効率であり、レビューのノイズとなります。本プロジェクトでは、ツールによって規約の遵守を強制します。各ツールの設定は、リポジトリのルートに配置された
.sqlfluff ファイル（SQL専用フォーマッター・リンター設定）、および
package.json
ファイル（依存関係・スクリプト管理）で一元管理します。また、エディタレベルでの基本的な設定は
.editorconfig ファイルで統一します。
- フォーマッター:
- 役割: インデント、スペース、キーワードの大文字化などを自動で統一します。
- 推奨ツール:
SQLFluff: SQL専用のリンター兼フォーマッター。多くのSQL方言をサポートし、詳細な設定が可能です。Prettier(with SQL plugin): Web開発で利用しているPrettierにSQLプラグイン (prettier-plugin-sql) を追加することで、SQLファイルも同じツールでフォーマットできます。- その他、DataGripやDBeaverなどのSQLクライアントに内蔵されているフォーマッターも活用します。
!!! success "CI/CDによる自動チェック" - GitHub
Actionsのワークフローにsqlfluff lintおよびsqlfluff format --checkを組み込むことで、SQLファイルのフォーマットとスタイルが規約に違反しているコードのマージを自動的にブロックします。-
SQLクライアントツールの自動フォーマット機能を活用することを推奨します。
3. フォーマットとインデント (Formatting and Indentation)
- インデント:
JOIN句やサブクエリなど、階層が深くなる場合は、半角スペース2つまたは4つでインデントします。（プロジェクト内で統一）
- 主要な句は改行:
SELECT,FROM,WHERE,GROUP BY,ORDER BYなどの主要な句は、それぞれ新しい行から書き始めます。
- カンマの位置:
SELECT句のカラムリストなどは、カンマを要素の前に置く「リーディングカンマ」スタイルを推奨します。これにより、コメントアウトや項目の追加・削除が容易になります。
良い例 (リーディングカンマ):
SELECT
u.id
, u.name
, u.email
, COUNT(p.id) AS post_count
FROM
users AS u
LEFT JOIN
posts AS p ON u.id = p.user_id
WHERE
u.is_active = TRUE
AND u.created_at >= '2023-01-01'
GROUP BY
u.id
, u.name
, u.email
ORDER BY
post_count DESC;
4. 命名規則 (Naming Conventions)
この命名規則は、02.設計仕様/02.データ仕様/01_データモデル設計書で定義されるルールと一致させます。
- テーブル名:
- 小文字のスネークケース (
snake_case) を使用します。 - テーブルが表すエンティティの複数形とします。（例:
users,posts,order_items）
- 小文字のスネークケース (
- カラム名:
- 小文字のスネークケース (
snake_case) を使用します。 idや、外部キーを示すuser_idのような、明確で一貫性のある名前を付けます。
- 小文字のスネークケース (
- エイリアス (別名):
- テーブルやカラムにエイリアスを付ける場合は、
ASキーワードを明記することを推奨します。 - エイリアス名は、元の名前の頭文字など、短く分かりやすいものにします。（例:
users AS u,posts AS p）
- テーブルやカラムにエイリアスを付ける場合は、
5. その他 (Miscellaneous)
JOINの明示:JOINを記述する際は、INNER JOIN,LEFT JOINのように、結合の種類を常に明示します。単にJOINと書くのは避けてください。
- ワイルドカード (
*) の不使用:SELECT *は、意図しないカラムの取得やパフォーマンス低下の原因となるため、原則として使用を禁止します。- 必ず、取得したいカラム名を全て明示的に記述してください。
- コメント:
- 複雑なクエリや、特定のロジックには、
--（一行コメント）や/* ... */（複数行コメント）を使って、その意図を説明するコメントを記述します。
- 複雑なクエリや、特定のロジックには、