flutter-drift

Flutter Drift

Flutter アプリに Drift ベースのローカル永続化を追加または修復する際に、このスキルを使用してください。このスキルは作業手順です。まず対象アプリを調査し、関連する参照ファイルだけを選び、現在の Drift API を使って実装し、生成されたコードを検証します。

基本的なワークフロー

1. 編集する前にアプリを調査します。
   • pubspec.yaml、既存のデータベースファイル、build.yaml、状態管理パッケージ、対象プラットフォーム、テストを確認します。
   • このスキルの例よりも、アプリで現在使われているアーキテクチャと命名を優先します。
2. バージョンをハードコードせず、パッケージコマンドで依存関係を追加または確認します。
   • dart pub add drift drift_flutter path_provider dev:drift_dev dev:build_runner
   • provider または flutter_riverpod は、アプリですでに使用している場合、またはユーザーから連携を求められた場合にのみ追加します。
3. データベースのエントリーポイントを作成または更新します。
   • Dart または .drift ファイルでテーブルを定義します。
   • テーブルを @DriftDatabase に追加します。
   • プロジェクトでカスタムエグゼキューターが必要な場合を除き、package:drift_flutter/drift_flutter.dart の driftDatabase を使用して Flutter データベースを開きます。
4. Drift の呼び出しはデータベースオブジェクトのスコープ内に保ちます。
   • ウィジェット、サービス、リポジトリでは、database.select(database.todoItems)、database.into(database.todoItems)、database.update(database.todoItems)、database.delete(database.todoItems) を使用します。
   • select(todoItems) のように単独で呼び出すのは、メソッドとテーブルゲッターがスコープ内にある GeneratedDatabase のサブクラスまたは DatabaseAccessor クラス内に限ります。
5. Drift の宣言を変更した後はコードを生成します。
   • dart run build_runner build を実行します。
   • ジェネレーターのエラーは任意の後処理ではなく、解消必須の問題として扱います。
6. 既存アプリのスキーマを変更する場合は、Drift のガイド付きマイグレーションワークフローを使用します。
   • build.yaml で drift_dev データベースを設定します。
   • 必要に応じて、スキーマ変更の前後に dart run drift_dev make-migrations を実行します。
   • schemaVersion を引き上げ、生成されたステップごとのマイグレーションを記述し、生成されたマイグレーションテストを実行します。
7. 完了前に検証します。
   • 編集した Dart ファイルに対して dart format を実行します。
   • パッケージに対して flutter analyze または dart analyze を実行します。
   • マイグレーションを変更した場合は生成されたマイグレーションテストも含め、対象を絞ったテストを実行します。

リソースの振り分け

• Drift の追加、データベースのオープン、Web サポートの設定、または分離したアイソレート間でのデータベース共有を行う場合は、references/setup.md を読みます。
• テーブル、列、デフォルト値、キー、インデックス、制約、生成列、または厳密なテーブルを定義する場合は、references/tables.md を読みます。
• セレクト、フィルター、ソート、ページネーション、結合、集計、サブクエリ、カスタム列、またはユニオンを実装する場合は、references/queries.md を読みます。
• 挿入、更新、削除、アップサート、コンパニオン、トランザクション、または一括操作を実装する場合は、references/writes.md を読みます。
• リアクティブな Drift ストリーム、StreamBuilder、StreamProvider、カスタムセレクトストリーム、テーブル更新リスナー、または手動でのストリーム無効化を実装する場合は、references/streams.md を読みます。
• schemaVersion、既存のユーザーデータ、build.yaml、make-migrations、生成されたスキーマファイル、またはマイグレーションテストが関係する場合は、references/migrations.md を読みます。
• Provider、Riverpod、StreamBuilder、検索、フィルタリング、ページネーション、またはユーザー向けの読み込み状態やエラー状態を使って Drift データを Flutter ウィジェットに連携する場合は、references/flutter-ui.md を読みます。

必須の API ルール

• ウィジェットからトップレベル関数として select(database.table) を呼び出さないでください。データベースクラスの外部では、database.select(database.table) を使用してください。
• watch(...)、todoUpdates(...)、notifyTableUpdates(...) は使用しないでください。customSelect(...).watch()、tableUpdates(...)、notifyUpdates(...) を使用してください。
• delete(table).go(id) は呼び出さないでください。where 句を追加してから go() を呼び出すか、プロジェクトですでに使用している場合は生成されたテーブル拡張ヘルパーを使用してください。
• batch.updateAll(...) を使用したり、生の ID を batch.delete(...) に渡したりしないでください。batch.update(..., where: ...)、挿入可能な行を指定した batch.delete(...)、または batch.deleteWhere(...) を使用してください。
• Provider API と Riverpod API を混在させないでください。Provider.of<AppDatabase>(context) は provider に属し、Provider<AppDatabase>((ref) { ... }) と AsyncValue.when(...) は Riverpod に属します。
• 既存データベースのマイグレーション計画なしに schemaVersion を上げないでください。
• UI ストリームを更新する必要がある場合、生の SQLite 書き込みに依存しないでください。Drift の書き込み API を使用するか、明示的な TableUpdate メタデータを指定して notifyUpdates を呼び出してください。

代替手段

• パッケージのダウンロードがブロックされている場合は、ソースファイルを更新し、正確な dart pub add または flutter pub add コマンドをユーザー向けに記載してから、依存関係の解決が検証されていないことを伝えてください。
• プロジェクトで build_runner を実行できない場合、生成された *.g.dart ファイルを手書きしないでください。ソース宣言を修正し、ジェネレーターが実行できないことを報告してください。
• マイグレーションの状態が不明な場合は、schemaVersion を変更する前に作業を止め、現在リリース済みのスキーマ履歴またはデータベースファイルを確認してください。
• Web サポートが必要で、sqlite3.wasm と drift_worker.js が見つからない場合は、コードパスを追加し、必要な Web アセットを明示的に報告してください。

検証チェックリスト

• pubspec.yaml に Drift のランタイム依存関係とジェネレーター依存関係が含まれている。
• データベースファイルに、有効な part ディレクティブ、テーブル宣言、@DriftDatabase、コンストラクター、schemaVersion がある。
• クエリと書き込みの例がすべて、正しいデータベース／アクセサーのコンテキスト内に限定されている。
• build_runner で生成コードを再生成している。
• Flutter UI の例が、AsyncValue を List として扱わずに、読み込み中、空、エラー、データの各状態を処理している。
• マイグレーションは、生成されたスキーマスナップショット、段階的なマイグレーションコード、テストとともにのみ変更されている。
• 編集したパッケージで flutter analyze または dart analyze が成功するか、未解決のアナライザーエラーがあれば、その原因とともに報告されている。