lucid

Lucid

このスキルは、AdonisJS アプリケーションの Lucid データベース層で使用します。Lucid はデータベースファーストです。マイグレーションでデータベースを変更し、Lucid が database/schema.ts を生成します。モデルは生成されたスキーマクラスを拡張し、リレーションシップ、フック、スコープ、シリアライズ、ドメイン動作を宣言します。

タスクでコントローラー、ルート、バリデーター、ポリシー、サービス、または AdonisJS のより広範なアーキテクチャも扱う場合は、このスキルと併せて adonisjs を使用してください。Lucid の動作に関するテストを書く場合は、このスキルと併せて japa を使用してください。

基本ルール

• データベースを信頼できる唯一の情報源として扱います。
• スキーマの変更はマイグレーションに記述し、マイグレーションまたは schema:generate を実行して database/schema.ts を更新します。
• 生成された database/schema.ts を手動で編集しないでください。
• モデルファイルは通常、生成されたスキーマクラスを拡張し、リレーションシップ、フック、スコープ、シリアライズのオーバーライド、ドメインメソッドを含みます。
• SQL 中心のクエリ、レポート、単発スクリプト、またはモデルのハイドレーションが不要な場合は、db サービスを使用します。
• Active Record の動作、リレーションシップ、フック、スコープ、シリアライズ、またはモデルインスタンスが必要な場合は、モデルクエリを使用します。
• トランザクションの有効期間を関数の境界を越えて維持する必要がある場合を除き、db.transaction(async (trx) => ...) によるマネージドトランザクションを優先します。
• 破壊的な更新／削除クエリには、必ず where 句を指定します。
• ループ内でクエリを実行するのではなく、リレーションシップを事前ロードします。
• リレーションシップを考慮したフィルタリングや集計には、withCount、withAggregate、has、whereHas を使用します。

ワークフロー

永続化データを変更する機能を実装する場合：

1. 既存のテーブル、生成済みのスキーマクラス、モデル、リレーションシップを確認します。
2. まずマイグレーションを作成または更新します。
3. マイグレーションを実行するか、database/schema.ts の再生成に必要なコマンドを記載します。
4. モデルが生成されたスキーマクラスを拡張するように更新し、Lucid 固有の動作を追加します。
5. 規約と一致しない場合は、明示的なキーを指定してリレーションシップを追加または更新します。
6. アクセスパターンに応じて、クエリビルダー、スコープ、またはファクトリーを使用します。
7. リポジトリで利用可能な、対象を絞ったテストまたは型チェックコマンドで検証します。

既存データベースを採用する場合：

1. 接続を設定します。
2. schemaGeneration.excludeTables で管理対象外のテーブルを除外します。
3. node ace schema:generate を実行します。
4. アプリケーションが所有するテーブルに対してのみモデルを作成します。
5. スキーマルールまたはモデルレベルのオーバーライドで、規約との不一致に対処します。

適切な API の選択

必要な処理	推奨
テーブルの作成またはスキーマの変更	BaseSchema を使ったマイグレーション
型付きモデル列	database/schema.ts の生成済みスキーマクラス
行に対するドメイン動作	モデルメソッドとフック
リレーションシップの読み込み／フィルタリング	モデルクエリビルダー
レポートまたは SQL 中心の読み取り	db.from、db.query、Raw クエリビルダー
複数の書き込みの整合性	マネージドトランザクション
テストデータ	モデルファクトリー
初期データ／開発用データ	データベースシーダー

リファレンス

実装の前に、関連するローカルリファレンスを読み込んでください。

• マイグレーション、スキーマ生成、スキーマクラス、CRUD、スコープ、フック、シリアライズについては、references/schema-and-models.md を参照してください。
• db サービスのクエリ、モデルクエリビルダーの動作、ページネーション、Raw SQL、デバッグについては、references/query-builders.md を参照してください。
• マネージド／手動トランザクション、分離レベル、セーブポイント、行ロック、モデルのトランザクション、トランザクション内でのリレーションシップ書き込みについては、references/transactions.md を参照してください。
• belongsTo、hasOne、hasMany、manyToMany、hasManyThrough、事前ロード、リレーションシップフィルター、集計、書き込みについては、references/relationships.md を参照してください。
• テストデータベースの状態、ファクトリー、ファクトリーのリレーションシップ、中間テーブル属性、フック、シーダーについては、references/testing.md を参照してください。

各リファレンスには、まず基本的な実装パターンが記載されており、末尾には Lucid の公式ドキュメントへの詳しいリンクがあります。

アンチパターン

避けること	推奨する方法
database/schema.ts を手作業で編集する	マイグレーション、スキーマルール、またはモデルのオーバーライド
モデルファイルですべてのカラムを手動で宣言する	生成された *Schema クラスを拡張する
ループ内でリレーションシップのクエリを実行する	preload、ネストしたプリロード、withCount、withAggregate
スコープを指定せずに update または delete を実行する	常に明示的な where 条件を含める
単純な操作で手動トランザクションを使用する	管理された db.transaction コールバック
統合テストの対象となる処理で Lucid のクエリ動作をモックする	テスト用データベースとファクトリーを使って Japa を使用する
あらゆるレポートクエリでモデルを使用する	通常の行データで十分な場合は db サービスを使用する