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) を使用します。
   • メソッドとテーブルゲッターがスコープ内にある GeneratedDatabase サブクラスまたは DatabaseAccessor クラス内でのみ、ベアの select(todoItems) を使用します。
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 サポートを設定する場合、またはデータベースを複数の isolate 間で共有する場合は 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(...) を使用したり、batch.delete(...) に未処理 id を渡さないでください。batch.update(..., where: ...)、batch.delete(...) と挿入可能な行、または batch.deleteWhere(...) を使用します。
• Provider と 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 をリストとして扱わずに、ローディング、空、エラー、およびデータ状態を処理しています。
• マイグレーションは、生成されたスキーマスナップショット、ステップバイステップマイグレーションコード、およびテストのみで変更されました。
• 編集されたパッケージに対して flutter analyze または dart analyze が成功するか、残存するアナライザーエラーがブロッカーとともに報告されています。