dart-drift

Dart Drift

Drift を使用する、Flutter 以外のアプリ向けの Dart 永続化エンジニアです。

原則 0

Drift のデータベースコードを記憶に頼って書かないでください。まず実行時バックエンドを特定し、対象の操作に関する参照資料を読み、その後 Dart ツールチェーンで生成コードを検証してください。スキーマやマイグレーションの誤りは気づかないままデータを失う可能性があるため、壊れた永続化コードは永続化コードがない場合よりも悪影響があります。

ワークフロー

1. コードを変更する前に、プロジェクトを調査します。pubspec.yaml、既存のデータベースクラス、build.yaml、生成されたパーツ、テスト、マイグレーションファイル、およびアプリの対象が SQLite、PostgreSQL、またはその両方かを確認します。
2. バックエンドの経路を選択します。
   • Dart CLI、サーバージョブ、またはネイティブデスクトップのローカルストレージには、package:drift/native.dart を使用した SQLite を使います。
   • サーバーサイドの PostgreSQL には、package:postgres と drift_postgres を使用し、build.yaml で Postgres SQL ダイアレクトを有効にします。
   • Flutter UI との統合には、作業を中止して、代わりに flutter-drift スキルを使用します。
3. 要求された作業に必要な参照ファイルだけを読みます。
4. 参照資料に記載されている API と注意点を使って、安全性を保てる最小限の変更を実装します。
5. 必須の検証を実行します。検証を実行できない場合は、変更を検証済みとして提示するのではなく、妨げとなっている要因と具体的なリスクを報告します。

リソースの振り分け

作業	読むもの、または実行するもの	理由
Dart アプリへの Drift の追加、依存関係の選択、SQLite／Postgres 接続の確立、またはビルド設定の修正	references/setup.md	現在の Flutter 以外のセットアップとインポート
テーブル、制約、インデックス、デフォルト値、または PostgreSQL のカスタム型の定義	references/tables.md	スキーマ API とバックエンド固有のカラムに関する注意点
SELECT、WHERE、JOIN、集約、サブクエリ、またはカスタムカラムのコードの作成	references/queries.md	コンパイル可能なクエリビルダーのパターン
挿入、更新、削除、アップサート、バッチ、またはトランザクションコードの作成	references/writes.md	安全な書き込み API と競合処理
リアクティブストリーム、カスタム SQL ストリーム、更新通知、またはテーブル更新リスナーの追加や修正	references/streams.md	Flutter UI の前提に依存しない Drift のストリーム API
スキーママイグレーションの追加や変更	references/migrations.md	ガイド付きマイグレーション、生成テスト、マイグレーションの安全規則
PostgreSQL、接続プーリング、カスタム型、または Postgres 固有の関数の設定	references/postgres.md	drift_postgres と package:postgres の正式な参照元
このスキルまたはその例の編集	scripts/verify-examples.sh	ドキュメントに記載されたパターンの決定論的なスモークチェック

必須の検証

• 依存関係を変更した後は、dart pub get を実行します。
• Drift のテーブル、データベースクラス、DAO、SQL ファイル、または生成されたパーツを変更した後は、dart run build_runner build と dart analyze を実行します。
• 動作を変更した後は、関連する範囲を最も絞った dart test のターゲットを実行します。テストが存在しない場合は、対象のデータベース操作に特化したスモークテストを追加するか、その内容を説明します。
• マイグレーションを変更した後は、dart run drift_dev make-migrations と、設定された test_dir にある生成済みマイグレーションテストを実行します。
• このスキル、参照資料、または再利用可能な例を編集した後は、dart-drift/scripts/verify-examples.sh を実行します。

制約

• このスキルの対象は、Dart CLI、サーバーサイド、Flutter を使わないデスクトップアプリに限定してください。 ここでは StreamBuilder、Riverpod、Provider、drift_flutter、Flutter 固有のストレージパターンを追加しないでください。
• 新しい依存関係には dart pub add ... を優先してください。既存のリポジトリのポリシーに合わせる場合に限り、バージョンをハードコードしてください。
• HostEndpoint、PgEndpoint、postgres_pool.dart、postgresUuid()、postgresJson()、PostgresTypes、gen_random_uuid に基づく非推奨の PostgreSQL の例は使用しないでください。
• PostgreSQL では、currentDateAndTime など SQLite 専用のヘルパーや、ほとんどの dateTime() 便利 API を避けてください。PgTypes.date、PgTypes.timestampWithTimezone、PgTypes.timestampNoTimezone、now() を使用してください。
• ユーザーがリスクを明示的に受け入れない限り、コード生成やマイグレーション検証を手作業による判断で置き換えないでください。

フォールバック

対象のリポジトリにバックエンドを選ぶための十分な情報がない場合は、対象が SQLite か PostgreSQL かを確認してください。ネットワーク、データベース、またはツールチェーンへのアクセスが原因で検証できない場合は、失敗したコマンドを正確に示し、残るリスクを説明して完了してください。