704-technologies-sql

SQL のベストプラクティス

リレーショナルデータベースエンジン全般で、Java アプリケーション向けの保守性、安全性、パフォーマンスに優れた SQL をチームが作成できるよう支援します。

このスキルの対象範囲

• テーブル、カラム、インデックス、制約、ビュー、トリガー、ルーチンの命名規則
• リレーショナルテーブルの設計：キー、制約、タイムスタンプ、論理削除、正規化、方言に応じたデータ型
• クエリの作成：読みやすい書式、明示的なカラムリスト、結合、CTE、バインドパラメーター、実行計画の確認
• インデックス戦略：外部キー、フィルター／ソートのパス、複合インデックス、過剰なインデックス作成のリスク、インデックスのライフサイクル
• 本番データベース作業におけるセキュリティ、トランザクション、マイグレーション、テスト、モニタリングの実践

対象範囲： フレームワークに依存しない SQL の品質です。Java のデータアクセス API については、該当する JDBC、Spring Data JDBC、Panache、または Micronaut Data のスキルを参照してください。

制約

ユーザーが Java フレームワークとの統合を明示的に求めない限り、推奨事項は SQL とデータベース設計のレイヤーに限定してください。このリポジトリの XML ソースを編集した後は、スキルを再生成し、ビルドを検証してください。

• 必須：同じ変更セットで Java または Maven に関する変更を提案する前に、./mvnw compile または mvn compile を実行してください
• SQL インジェクション：信頼できない入力を SQL 文字列に連結しないでください。アプリケーションのデータアクセス API を通じてバインドパラメーターを使用してください
• 方言：PostgreSQL、MySQL、Oracle、SQL Server、H2、その他のエンジン固有の構文を使用する場合は、データベース固有の構文と移植性のトレードオフを明示してください
• フレームワーク：Spring JDBC は @311-frameworks-spring-jdbc、Quarkus JDBC は @411-frameworks-quarkus-jdbc、Micronaut JDBC は @511-frameworks-micronaut-jdbc、フレームワーク固有のマイグレーションは該当する Flyway スキルを参照してください
• 検証：変更を昇格する前に、./mvnw clean verify または mvn clean verify を実行してください
• エッジケース：対象のデータベース方言、マイグレーションツール、本番環境の制約が不明で、推奨内容に影響する場合は、SQL を編集する前に確認の質問をしてください
• エッジケース：要求された変更がデータの安全性、後方互換性、またはゼロダウンタイムデプロイの制約と相反する場合は、トレードオフを説明して確認を求めてください

このスキルを使う場面

• SQL スキーマまたはマイグレーションをレビューする
• SQL クエリのパフォーマンスと可読性を改善する
• リレーショナルテーブルとインデックスを設計する
• データベースのトランザクション、セキュリティ、またはモニタリングの実践をレビューする
• データベースの DDL または DML に SQL のベストプラクティスを適用する

ワークフロー

1. リファレンスを読み、データベースの状況を評価する

変更を提案する前に、references/704-technologies-sql.md を読み、現在のスキーマ、マイグレーション、SQL クエリ、テスト、データベース設定を確認してください。

2. 方言と運用上の制約を特定する

SQL 設計を左右する対象のデータベースエンジン、マイグレーションツール、想定データ量、可用性要件、互換性の制約を確認してください。

3. SQL に沿った変更を適用する

リファレンスのパターンとプロジェクトの規約に従って SQL アーティファクトを実装またはリファクタリングし、明示的に要求されない限り、Java フレームワークとの統合は対象外としてください。

4. 検証を実行して結果を報告する

適切なビルド、マイグレーション、SQL 検証、テストを実行してください。変更内容、検証した項目、残るデータベース上のリスクを要約してください。

リファレンス

詳細なガイダンス、例、制約については、references/704-technologies-sql.md を参照してください。