411-frameworks-quarkus-jdbc

Quarkus JDBC — プログラムによる SQL 操作

安全な SQL と明確なトランザクションを使用して、Quarkus でプログラムによる JDBC パターンを適用します。

このスキルで扱う内容

• 注入された javax.sql.DataSource（Agroal ベース）と、Connection / PreparedStatement に対する try-with-resources
• バインドパラメーターを使った PreparedStatement — 文字列連結は決して使用しない
• ResultSet の行を Java レコードにマッピング（専用の mapRow メソッド）
• Optional を使った安全な単一行クエリ — rs.next() が成功すると決めつけない
• SQLException をドメイン例外に変換（捕捉して変換し、再スロー）
• OOM を避けるため、setFetchSize を使って大規模な結果セットをストリーミング
• 一括挿入では addBatch / executeBatch を使ったバッチ更新
• @Transactional を使ったサービス境界と伝播タイプ（独立したコミットには TxType.REQUIRES_NEW）
• CDI の自己呼び出しに関する落とし穴：トランザクションメソッドは、必ず注入されたプロキシ経由で呼び出す
• 開発／テスト環境でのデータベース用 Dev Services
• Panache（@412）と生の JDBC のどちらを優先するか

範囲： 参考ルールと適切／不適切なコード例に基づいて推奨事項を適用します。

制約

JDBC のリファクタリング前にコンパイルし、変更後に検証してください。

• 必須：変更を適用する前に ./mvnw compile または mvn compile を実行する
• 前提条件：JDBC の改善を適用する前に、プロジェクトがコンパイルできること
• 安全性：コンパイルに失敗した場合は、直ちに中止する
• ブロッキング条件：コンパイルエラーは、作業を続ける前にユーザーが解決する必要がある
• 検証：改善を適用した後に ./mvnw clean verify または mvn clean verify を実行する
• 適用前：詳細なルールと例について、参考資料を読む

このスキルを使用する場面

• Quarkus プロジェクトの JDBC または SQL データアクセスをレビューする
• Quarkus JDBC のトランザクションとパラメーターのバインドを改善する
• SQLException をドメイン例外に変換する、または大規模な結果セットをストリーミングする
• Quarkus で @Transactional を迂回する CDI の自己呼び出しを修正する
• Quarkus JDBC での Agroal DataSource の使用方法をレビューする

ワークフロー

1. 参考資料を読み、プロジェクトの状況を評価する

変更を提案する前に references/411-frameworks-quarkus-jdbc.md を読み、現在のプロジェクト設定を確認します。

2. 範囲を把握し、対象とする改善を決める

要求されている成果と制約を特定し、適用する変更を安全な最小限に絞ります。

3. フレームワークに沿った変更を適用する

参考資料のパターンとプロジェクトの規約に従って、設定やコードを実装またはリファクタリングします。

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

適切なビルドやテストを実行し、変更内容、検証内容、フォローアップが必要な作業をまとめます。

参考資料

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