rust-database

Rust データベースレイヤーの提供

データベースの実際の方言、スキーマ、トランザクションセマンティクスに基づき、マイグレーション互換性があり、ロールバック可能で、可観測性を備えたデータアクセスレイヤーを提供します。HTTP ハンドラーをリポジトリとして扱わないでください。実際のデータベースの動作を検証するためにモックを使用しないでください。

データベースの契約の確認

変更を加える前に、以下を確認します。

• データベース製品、正確なバージョン、拡張機能、デプロイのトポロジー、読み取り／書き込みノードに関する情報を収集します。
• 現在のスキーマ制約、インデックス、トリガー、ビュー、マイグレーション履歴を確認します。
• SQLx、Diesel、SeaORM（またはその他のアクセススタック）の固定バージョンと、その機能を特定します。
• Rust ツールチェーン／MSRV、同期または非同期の実行モデルを確認します。
• 接続上限、インスタンス数、タイムアウト、トランザクション分離レベル、一貫性要件を確認します。
• データ量のプロファイル、頻繁に実行されるクエリ、ページネーション戦略、保持ポリシー、アーカイブの要件を定義します。
• 認証情報の取得元、TLS 構成、テナント境界、行レベルの権限、監査要件を文書化します。
• デプロイ時にダウンタイム、二重書き込み、バックフィル、破壊的な DDL 操作が許可されるかを明確にします。

実際のデータベースにアクセスできない場合は、「コード／オフラインのメタデータ検証」と「実際の方言の検証」を区別します。報告では、これら2つのアプローチを混同しないでください。

ワークフロー

1. 現状のベースラインを確立する

rustc --version --verbose
cargo metadata --format-version 1
cargo tree -e features
cargo test --all-targets

接続の初期化、プールの構成、リポジトリの実装、クエリ、マイグレーション、テスト用フィクスチャ、CI のデータベース接続を特定します。既存のマイグレーション状態確認／チェックコマンドを実行します。明示的な許可なしに、共有データベースを変更する操作は実行しないでください。

2. 既存のアクセススタックを維持する

SQLx、Diesel、SeaORM のいずれかに対する好みだけを理由に、書き換えることは避けます。現在のコードベースとタスク要件に応じて、適切なスタックを選択します。

• SQLx：SQL への直接アクセス、非同期クエリ、任意のコンパイル時クエリ検証が必要な場合に使用します。
• Diesel：型付き DSL クエリ、同期接続、または既存の Diesel スキーマを利用する場合に使用します。
• SeaORM：対応するマイグレーションシステムを備えた、非同期 ORM／エンティティモデルを利用します。
• ネイティブデータベースドライバー：プロトコルや機能が汎用レイヤーに対応していない場合に限り使用します。ただし、保守とセキュリティレビューの範囲が広がります。

具体的な選定基準と型の境界については、アクセススタックと型に記載されています。すべての API は Cargo.lock に記録されたバージョンのドキュメントに準拠させ、最新の例をレガシープロジェクトにそのまま適用しないでください。

3. スキーマ制約で事実を保証する

• データベースが保証する変更不可能な不変条件として、主キー、一意性制約、外部キー、NOT NULL 制約、CHECK 制約を定義します。
• Rust の型はドメインの意味を表現しますが、データベースが提供するプロセス間の並行性保証に取って代わることはできません。
• 整数幅、小数精度、タイムゾーン、UUID、JSON 形式、NULL 許容性のマッピングを明示的に指定します。
• すべてのクエリでバインドパラメーターを使用します。動的な識別子やソートフィールドを使用する場合は、通常のバインド値を安全なものとして扱うのではなく、許可リストと型マッピングを通じてのみ指定します。
• 不安定な SELECT * の列構成に依存しないよう、必要な列だけを選択します。
• データ量が多い場合は、無制限のオフセット操作より、安定したソート方法とキーセット方式のページネーションを優先します。

4. コード変更前にマイグレーションを設計する

スキーマを変更する場合は、次の内容を文書化してください。

1. 前進用の DDL 文。
2. アプリケーションにおける旧バージョンと新バージョンの互換性維持期間。
3. データのバックフィル方法、バッチサイズ、ロールバック地点。
4. インデックス構築のリスクとロック競合への影響。
5. ロールバックまたは前進復旧の戦略。
6. 検証クエリ、監視メトリクス、終了条件。

expand → backfill → switch → contract の順序を採用してください。カラムの削除、型の変更、大規模なテーブル再構築、データの消去、不可逆なバックフィルなどの破壊的操作には、Migrations and Schema Evolution に記載されている、明示的な対象の解析と認可の詳細が必要です。

5. トランザクションを一連のユースケースに含める

• トランザクションはアプリケーションサービスまたはリポジトリのユニットオブワークから開始し、HTTP ハンドラーをむやみにまたいでトランザクションをコミットしないでください。
• 1 つの共有トランザクションと接続セット内の書き込みは、すべてアトミックに成功するようにしてください。
• 不要な外部 HTTP 応答待ちなど、トランザクションの範囲外でユーザーとのやり取りを無制限に待たないでください。
• データベースのドキュメントに従って分離レベルを選択し、更新の消失、書き込みスキュー、ファントムリードなどのリスクを特定してください。
• データベースが明示的に一時的なエラーとして特定した場合に限り、再試行してください。再試行回数、バックオフ戦略、冪等性の境界を設定してください。
• コミットが失敗する可能性があります。「最後の SQL 文が成功した」ことをトランザクションの完了とみなさないでください。
• ロールバックは安全網として機能しますが、明示的な制御フローの設計やテストの代わりにはなりません。

接続プーリング、分離レベル、再試行メカニズムの詳細は、Transactions and Pooling を参照してください。

6. 安定したデータアクセスインターフェースを設計する

application use case
  -> repository / unit of work port
  -> SQL/ORM adapter
  -> database

• リポジトリのメソッドは、Web DTO を漏出させず、ドメインパラメーターとドメインの戻り値を受け取るようにしてください。
• エラーを、見つからない場合、一意性の競合、外部キー違反、シリアライズエラー、タイムアウト、利用不可のカテゴリに分類してください。
• ログと診断ではエラーチェーン全体を保持しつつ、ユーザーへの応答に機密性の高い SQL パラメーターが含まれないようにしてください。
• バッチインターフェースでは、順序の意味、部分的な失敗の処理、冪等性の保証を定義し、行数を返すようにしてください。
• N+1 クエリを避けてください。事前読み込みの結合やバッチ処理が必要な場合は、現実的なデータ規模でパフォーマンスを検証してください。

7. 接続数の予算を制限する

次の式を使って、接続数の合計予算を検証してください。（インスタンスごとのプール上限 × インスタンスの最大数）+ 運用上の接続数。接続の取得、接続、ステートメント、トランザクションの各タイムアウトを設定し、アイドル時および最大の接続ライフタイム、ヘルスチェック、正常なシャットダウン手順を定義してください。リクエストごとに新しいプールを作成したり、無期限の待機によってリソース枯渇の問題を隠したりしないでください。

8. 実際のデータベースエンジンで検証する

少なくとも次の検証を実施してください。

1. 空のデータベースに対してすべてのマイグレーションを実行します。
2. 既存のデータベースがサポートするスキーマバージョンをアップグレードします。
3. リポジトリの成功、レコードが見つからない場合、制約の競合、型の境界値を検証します。
4. トランザクションのコミット、ロールバック、コミット失敗、再試行可能な同時実行の問題をテストします。
5. 同時書き込みが行われても不変条件が維持されることを確認します。
6. クエリプラン、インデックスの使用状況、代表的なデータ量を確認します。
7. プール枯渇のシナリオ、データベースの再起動や切断、正常なシャットダウン時の動作を評価します。
8. ログ、メトリクス、トレースにバインド値や認証情報が漏れていないことを確認します。

テストの実行方法と運用項目については、Testing and Operations を参照してください。

共通ゲート（ゲートウェイ）

cargo fmt --all -- --check
cargo check --all-targets
cargo test --all-targets
cargo clippy --all-targets -- -D warnings

リポジトリ固有のマイグレーション検証、SQLx のオフラインメタデータチェック、Diesel のスキーマ監査、または実際のデータベースとの統合テストを実行してください。コマンドや機能はバージョンによって異なる場合があります。まずプロジェクトの設定を確認してください。

完了基準

• データベースのバージョン、スキーマ、アクセススタック、一貫性に関する前提が明確に定義されていること。
• すべてのクエリでパラメーター化を使用し、動的な識別子は許可リストでフィルタリングされていること。
• マイグレーションの互換性期間、バックフィル戦略、復旧手順、破壊的変更の境界が文書化されていること。
• トランザクションがユースケース全体を対象とし、接続数の上限とタイムアウトが妥当な根拠とともに設定されていること。
• 実データベースを使ったテストで、マイグレーション、制約、ロールバック、並行処理に伴うリスクが検証されていること。
• fmt、check、test、Clippy が成功すること。実データベースを使ったテストで未検証の項目は、明示的にその旨を記載すること。

引き継ぎの境界

主な責任	担当
HTTP ルーティング、ハンドラー、ステータスコード、ミドルウェア	rust-web
認証情報、テナント認可、監査ログ、機密フィールドの公開	rust-web-security
非同期キャンセル、ロック、タスク、ブロッキング処理の分離	rust-concurrency
テストの階層化、カバレッジ指標、パフォーマンスのベースライン	rust-testing
機能、ビルドスクリプト、オフラインメタデータ、リリースパイプライン	rust-cargo-build
型、所有権のセマンティクス、エラートレイト、標準ライブラリの動作	rust-stable

必要に応じて参照するリソース

• アクセススタックと型：SQLx、Diesel、SeaORM、または型マッピングを選択または調整する際に参照してください。
• マイグレーションとスキーマの進化：DDL の設計、互換性を保つバックフィル、復旧戦略を確認してください。
• トランザクションとプーリング：原子性の保証、分離レベル、再試行ロジック、容量管理の参考にしてください。
• テストと運用：実データベースを使ったテストのセットアップ、クエリプラン、可観測性の実践方法を参照できます。
• シナリオ例：エンドツーエンドのタスク分解が必要な場合は、このテンプレートを使用してください。
• examples/golden-transaction/：トランザクション境界の例について、オフラインでのコンパイルと検証をここで実施できます。

参考資料

• std::error（Rust 標準ライブラリ）
• SQLx ドキュメント
• Diesel ガイド
• SeaORM ドキュメント