Drift (Moor) — co to jest, reaktywny ORM i praca z bazami danych

Czym jest Drift?

Drift — ORM dla Dart i Flutter, wcześniej znany jako Moor. Został opracowany przez Simona Binder w 2019 roku i przeszedł kilka głównych wersji. Drift kompiluje zapytania Dart do SQL na etapie budowania za pomocą drift_dev i build_runner, co zapewnia pełną bezpieczeństwo typowe i eliminuje błędy składniowe SQL w runtime.

W przeciwieństwie do Floor, Drift używa własnego DSL (Domain-Specific Language) do budowania zapytań — programista pisze w Dart, a generator tłumaczy to na SQL. Pozwala to IDE sprawdzać składnię, autouzupełniać pola tabel i refaktorować model danych bez obawy o zepsucie zapytania.

Według Drift (2024), biblioteka jest używana w ponad 8000 projektów Flutter. Obsługuje wszystkie popularne platformy: Android przez sqflite, iOS przez sqflite, web przez sqlite3 WASM, desktop przez natywny sterownik sqlite3.

Historia zmiany nazwy: Moor → Drift

Moor został przemianowany na Drift w wersji 2.0 (2022). Powodem był konflikt nazw z innymi projektami i chęć zdystansowania się od starego kodu. API pozostało kompatybilne: do migracji wystarczy zastąpić import z moor na drift i zaktualizować zależności.

Kluczowe możliwości

Drift zapewnia: wbudowane zapytania Stream z automatyczną aktualizacją przy zmianie danych, obsługę transakcji z wycofywaniem, niestandardowe zapytania SQL przez rawQuery, wzorzec DAO do enkapsulacji logiki, wieloplatformowe migracje oraz integrację z Riverpod i BLoC przez pakiety drift_riverpod i drift_bloc.

Jak działa Drift?

Drift używa generowania kodu na etapie kompilacji. Programista opisuje tabele przez adnotacje @DataClass lub klasy Dart rozszerzające Table. Generator tworzy klasy pomocnicze: Companion (dla pól nullable przy wstawianiu/aktualizacji), DriftDatabase (punkt wejścia) i implementacje DAO.

Zapytania SQLite Drift nie wykonuje bezpośrednio. Zamiast tego programista pisze w Dart: select(tasks).where(tasks.priority.greaterThan(3)).build(). Generator tłumaczy to na SQL, a w czasie wykonania Drift po prostu wysyła gotowe zapytanie SQL do SQLite. Łączy to wygodę składni Dart z wydajnością natywnego SQL.

Architektura zapytań

Drift obsługuje dwa tryby zapytań: DSL (zalecany) i raw SQL. Zapytania DSL są bezpieczniejsze w pisaniu — kompilator sprawdza nazwy pól, typy i kompatybilność. Raw SQL jest potrzebny do złożonych zapytań nieobjętych DSL: funkcje okienne, rekurencyjne CTE, specyficzne rozszerzenia SQLite.

Drift DSL vs SQL: porównanie podejść

Drift oferuje dwa sposoby pisania zapytań: Dart DSL (natywny) i raw SQL (dla złożonych przypadków). DSL jest preferowany w 90% scenariuszy: jest bezpieczniejszy, bardziej czytelny i obsługuje refaktoryzację. Raw SQL jest używany tylko wtedy, gdy DSL nie obejmuje wymaganej konstrukcji.

Kiedy używać DSL

Drift DSL — główny sposób pracy. Obejmuje SELECT, INSERT, UPDATE, DELETE, WHERE, ORDER BY, LIMIT, JOIN i grupowanie. Do wszystkich typowych zapytań CRUD używaj DSL: jest krótszy, bezpieczniejszy i automatycznie aktualizuje Stream przy zmianach.

Kiedy używać raw SQL

Raw SQL w Drift jest potrzebny do: niestandardowych funkcji SQLite (FTS5, JSON1), złożonych podzapytań z EXISTS, INSERT OR REPLACE, masowych UPDATE z CASE, a także do zapytań, w których wydajność jest krytyczna i DSL nie generuje optymalnego planu wykonania. Raw SQL można pisać w plikach .sql z obsługą typizacji przez drift_dev.

Przykłady kodu z Drift

Drift używa klas rozszerzających Table lub adnotacji @DataClass. Poniżej — pełny przykład modelu Task z zapytaniami przez DSL, raw SQL i reaktywną aktualizacją. Po uruchomieniu build_runner, wszystkie wygenerowane klasy są gotowe.

Definiowanie tabeli i bazy danych

Klasa Tasks rozszerza Table i definiuje kolumny. Każda kolumna to wyrażenie typu Column<T>. Parametry: withDefault() ustawia wartość domyślną, autoIncrement() — autoinkrementację. Baza danych to abstrakcyjna klasa rozszerzająca $DriftDatabase.

class Tasks extends Table {
    IntColumn get id => integer().autoIncrement();
    TextColumn get title => text().withDefault(const Constant(''))();
    BoolColumn get isCompleted => boolean().withDefault(const Constant(false))();
    IntColumn get priority => integer().withDefault(const Constant(0))();
}

@DriftDatabase(tables: [Tasks])
class AppDatabase extends $AppDatabase {
    AppDatabase(QueryExecutor e) : super(e);
}

Operacje CRUD przez DSL

Drift generuje metody into(tasks).insert(), select(tasks), update(tasks) i delete(tasks) dla tabel. Wszystkie operacje zwracają Future — praca z SQLite jest asynchroniczna. Do śledzenia zmian używaj .watch() zamiast .get().

// Zapis
await into(tasks).insert(TasksCompanion.insert(
    title: Value('Kup produkty'),
    priority: Value(3),
));

// Odczyt z filtrem
final highPriority = await (select(tasks)
    ..where((t) => t.priority.greaterThan(2))
    ..orderBy([(t) => OrderingTerm(expression: t.priority, mode: OrderingMode.desc)]))
    .get();

// Obserwacja reaktywna
select(tasks).watch().listen((tasksList) {
    // tasksList — List, aktualizowana przy każdej zmianie tabeli
    updateUi(tasksList);
});

Raw SQL z typowanym wynikiem

Dla złożonych zapytań Drift pozwala pisać raw SQL, zachowując typowanie. Metoda customSelect przyjmuje łańcuch zapytania i zwraca typowany wynik przez generator kodu. Takie podejście łączy elastyczność SQL z bezpieczeństwem typów Drift.

final result = await customSelect(
    'SELECT title, COUNT(*) as cnt FROM tasks GROUP BY title',
    readsFrom: { tasks },
).get();

for (final row in result) {
    print('${row.readString("title")}: ${row.readInt("cnt")}');
}

Migracje i wersjonowanie w Drift

Drift obsługuje zarówno automatyczne migracje (dla prostych zmian), jak i ręczne (dla złożonych transformacji). Wersja bazy jest ustawiana w konstruktorze AppDatabase. W przypadku niezgodności wersji, Drift stosuje wszystkie niezamknięte migracje sekwencyjnie.

Automatyczne migracje

Do dodania kolumny z wartością domyślną Drift może wygenerować migrację automatycznie przez MigrationStrategy. Jeśli zmiana nie narusza istniejących danych (dodanie pola nullable), można użyć beforeOpen ze sprawdzeniem wersji i wykonaniem ALTER TABLE.

Ręczne migracje

Do złożonych zmian (zmiana nazwy tabeli, łączenie danych, zmiana typu kolumny) Drift wymaga ręcznej migracji SQL. Migracje są określane przez parametr migrations w klasie bazy danych. Każda migracja to obiekt z numerami from/to i zapytaniami SQL.

Drift i testowanie

Drift obsługuje uruchamianie w trybie testowym przez NativeDatabase.memory(). Baza w pamięci jest tworzona od nowa przed każdym testem i niszczona po. Do mockowania używaj pakietu mocktail z zamockowanym QueryExecutor. Drift udostępnia również DatabaseTestHelper do testów integracyjnych z weryfikacją migracji i zapytań.

Wzorzec DAO w Drift

Drift obsługuje DAO (Data Access Object) przez abstrakcyjne klasy z adnotacją @DriftAccessor. DAO enkapsuluje zapytania do jednej lub wielu tabel i może być testowany oddzielnie od bazy danych. W przeciwieństwie do bezpośrednich zapytań przez Database, DAO pozwala ponownie używać logiki zapytań między różnymi częściami aplikacji i upraszcza testowanie modułowe.

@DriftDatabase(tables: [Tasks])
class AppDatabase extends $AppDatabase {
    AppDatabase(QueryExecutor e) : super(e) {
        migrations.add(Migration(1, 2, (m) async {
            await m.addColumn(tasks, tasks.dueDate);
            await m.createIndex(tasks.idxPriority);
        }));
    }
}