rust-sqlx-postgres-service

Rust SQLx Postgres サービス

このスキルは、Rust/Postgres の変更をスキーマ優先で進め、コンパイル時に検証し、テスト可能にするために使用します。明示的なマイグレーション、注入されたプール、役割を絞ったリポジトリ関数、ビジネス操作に合ったトランザクション境界を優先してください。

基本的なワークフロー

1. コードを変更する前に、Cargo.toml、migrations/、.sqlx/、docker-compose.yml、CI、既存のデータベースヘルパーモジュールを確認します。
2. まずスキーマ変更を設計します。依存するリポジトリコードを書く前に、マイグレーションを作成または更新します。
3. コンパイル時に SQL が検証される sqlx::query! と query_as! を優先します。動的 SQL は、クエリの形が実行時に本当に変わる場合にのみ使用します。
4. PgPool、PgConnection、または Transaction を明示的に注入します。ハンドラーやリポジトリ関数内でプールを作成しないでください。
5. リポジトリ関数は小さく保ち、振る舞いに基づいて命名します。アプリ全体に生の行データを漏らさず、ドメイン型または永続化用 DTO を返します。
6. 複数の処理をまとめてコミットまたはロールバックする必要がある場合は、トランザクションを使用します。
7. 変更が API の意味に影響する場合は、マイグレーションを実行し、公開されている振る舞いを検証する統合テストを追加または更新します。
8. 同梱の事前チェック用スクリプト、またはリポジトリで同等の SQLx/Cargo CI コマンドを実行します。

マイグレーションのルール

既存のテーブルやデータを変更する前に、references/migration-safety.md を読んでください。

マイグレーションでは、次の方針をデフォルトで優先します。

• まずは追加的な変更を行います。新しい NULL 許容カラム、新しいテーブル、新しいインデックスなどです。
• テーブルが大規模な可能性がある場合は、スキーマの作成とは別にバックフィルを行います。
• 既存データが条件を満たしてから、not null、一意性、外部キーの制約を追加します。
• エラーや運用時に表示される制約とインデックスには、意図が伝わる名前を付けます。
• プロジェクトで down マイグレーションを使用している場合は維持します。使用していない場合は、マイグレーションレビューにロールバック時の想定を記載します。

クエリのルール

SQLx マクロ、トランザクション、オフラインモードの詳細については、references/sqlx-patterns.md を読んでください。

• 文字列補間よりバインドパラメーターを優先します。
• キーによる検索には fetch_optional を使用します。
• 行データが不要な挿入や更新には execute を使用します。
• 呼び出し元が生成された ID やタイムスタンプを必要とする場合は RETURNING を使用します。
• 常に1行だけを対象とする更新や削除では、影響を受けた行数を確認します。
• データベースの一意性違反は、リポジトリ境界付近でドメインエラーに変換します。

検証

標準的な SQLx ワークフローを適用できる場合は、Rust プロジェクトのルートから実行します。

path/to/rust-sqlx-postgres-service/scripts/sqlx-preflight.sh

このスクリプトは慎重に動作します。フォーマットとテストを確認し、CLI と DATABASE_URL が利用可能な場合は SQLx のマイグレーション状態を調べます。また、.sqlx/ または DATABASE_URL が利用可能な場合は cargo sqlx prepare --check で SQLx オフラインメタデータを検証します。マイグレーションを適用するのは、RUST_SQLX_PREFLIGHT_RUN_MIGRATIONS=1 が設定されている場合のみです。

リポジトリで別の CI コマンドを使用している場合は、そのコマンドを使い、理由を説明してください。

参照ファイル

• references/sqlx-patterns.md：query!、query_as!、プール、トランザクション、機能フラグ、オフラインモード。
• references/migration-safety.md：安全なマイグレーションの順序とロールアウトの確認。