flutter-drift

Flutter Drift

Use this skill to add or repair Drift-based local persistence in Flutter apps. The skill is an operating workflow: inspect the target app first, choose only the relevant reference files, implement with current Drift APIs, and validate generated code.

Core Workflow

1. Inspect the app before editing:
   • Check pubspec.yaml, existing database files, build.yaml, state management package, target platforms, and tests.
   • Prefer the app's current architecture and naming over the examples in this skill.
2. Add or verify dependencies with package commands instead of hardcoding versions:
   • dart pub add drift drift_flutter path_provider dev:drift_dev dev:build_runner
   • Add provider or flutter_riverpod only when the app already uses it or the user asks for that integration.
3. Create or update the database entry point:
   • Define tables in Dart or .drift files.
   • Add the tables to @DriftDatabase.
   • Open Flutter databases with driftDatabase from package:drift_flutter/drift_flutter.dart unless the project needs a custom executor.
4. Keep Drift calls scoped to the database object:
   • Use database.select(database.todoItems), database.into(database.todoItems), database.update(database.todoItems), and database.delete(database.todoItems) from widgets, services, and repositories.
   • Use bare select(todoItems) only inside GeneratedDatabase subclasses or DatabaseAccessor classes where the methods and table getters are in scope.
5. Generate code after changing Drift declarations:
   • Run dart run build_runner build.
   • Treat generator errors as blockers, not optional cleanup.
6. For schema changes in an existing app, use Drift's guided migration workflow:
   • Configure drift_dev databases in build.yaml.
   • Run dart run drift_dev make-migrations before and after schema changes as needed.
   • Bump schemaVersion, write generated step-by-step migrations, and run generated migration tests.
7. Validate before finishing:
   • Run dart format on edited Dart files.
   • Run flutter analyze or dart analyze for the package.
   • Run targeted tests, including generated migration tests when migrations changed.