Persistence, SQLite & Offline-First Data — Flutter Course

What you'll learn

Design durable local data with migrations, transactions, caching, optimistic writes, sync queues, and explicit conflict policies. The lesson turns the APIs into a repeatable engineering workflow instead of a collection of isolated snippets.

By the end of this lesson, you'll be able to:

Apply Storage choices in a production-shaped Flutter feature
Apply SQLite schema in a production-shaped Flutter feature
Apply Migrations in a production-shaped Flutter feature
Apply Repository source of truth in a production-shaped Flutter feature

Core mental model

Connect each API to the decision it supports. Flutter code stays maintainable when state, ownership, lifecycle, and platform boundaries are explicit.

Concept	What it means	Decision rule
Source of truth	The authoritative state observed by the rest of the app	Expose one repository stream even when data comes from local and remote stores
Migration	A versioned transformation of persisted schema and data	Make it forward-only, tested on real prior versions, and recoverable
Conflict policy	A deterministic rule for concurrent local and remote edits	Choose per domain field instead of relying blindly on last write wins

Professional workflow

Work in small vertical slices and keep behavior observable from the first iteration.

Define the offline-first progress repository boundary: user goal, inputs, visible states, ownership, and expected failures.
Build the smallest working vertical slice with typed data and explicit dependencies.
Represent loading, empty, success, and failure behavior where the feature can encounter them.
Verify logic away from the UI, then exercise the rendered behavior at its public boundary.
Inspect lifecycle, accessibility, performance, security, and platform behavior before widening the feature.
Refactor only after behavior is protected by repeatable evidence.

Protect the frame

Keep build methods predictable, move side effects to explicit owners, and measure before introducing caches, isolates, or architectural layers.

Guided Flutter lab

Build a focused offline-first progress repository slice

This compact example keeps the important ownership and data-flow decisions visible so the behavior is easy to extend and test.

lib/data/offline_progress_repository.dart

class OfflineProgressRepository {
  OfflineProgressRepository(this.local, this.remote);
  final ProgressStore local;
  final ProgressApi remote;

  Stream<List<Progress>> watchAll() => local.watchAll();

  Future<void> complete(String lessonId) async {
    final change = PendingChange.complete(lessonId, DateTime.now().toUtc());
    await local.transaction(() async {
      await local.apply(change);
      await local.enqueue(change);
    });
    unawaited(sync());
  }

  Future<void> sync() async {
    for (final change in await local.pendingChanges()) {
      await remote.push(change);
      await local.markSynced(change.id);
    }
  }
}

Production practice

Contract

Define the offline-first progress repository inputs, outputs, owner, lifecycle, visible states, and platform assumptions before selecting APIs or packages.

Verification

Protect pure rules with unit tests and the rendered public contract with widget or integration evidence; include one unavailable or failure case.

Operations

Keep dependencies replaceable, log actionable context without user secrets, and measure user-visible behavior before optimizing.

Common failure mode

Using connectivity status as proof that a request will work creates false certainty; attempt the operation, classify failure, and retain durable pending work.

Independent workshop

Extend the guided lab into a review-ready offline-first progress repository feature that fits the running course portfolio app.

Your finished workshop must include:

Storage choices
SQLite schema
Migrations
Repository source of truth
Offline sync
Automated verification and a short design note

Definition of done

Demonstrate the happy path, an empty or unavailable state, and at least one failure path. Add an automated check and a short note explaining one design decision.

Recap & quick check

Key takeaways

Source of truth: Expose one repository stream even when data comes from local and remote stores
Migration: Make it forward-only, tested on real prior versions, and recoverable
Conflict policy: Choose per domain field instead of relying blindly on last write wins

Quick check

1. Which rule best applies to Source of truth?

2. Which rule best applies to Migration?

3. Which rule best applies to Conflict policy?

Next: State Management & Dependency Injection