← Flutter / Dart

Flutter / Dart · 21 / 24

Drift migrations with existing data

Open a version 1 database with version 2 and preserve existing records.

  • Large
  • Advanced
  • 90 min

Prerequisites: Understand SQL and place Drift/SQLite in context

In this tutorial
  1. Define the boundary
  2. Set up the learning project
  3. Trace the successful outcome
  4. Observe failures deliberately
  5. Solve the extension
  6. Compare the solution
  7. Exercise and solution
  8. Project context and sources

Download learning package

Setup and verification

Flutter 3.41.5 or newer with Dart 3.11. Python 3 is also required for the common verification entry point. Extract the learning package into a new folder and run python3 run_checks.py there. The script copies the included files into a temporary learning directory. It verifies the example and then the supplied solution there, preserving the original files. Required packages are downloaded on the first run.

Verified on 2026-10-20 on Linux x86_64. Check that old names survive, archived receives its default and reopening needs no second upgrade. Deleting the file would not test migration.

A fresh database does not test an upgrade path. The test first creates a real file containing the previous schema and a record. It then opens the same file using the new version. The new default must apply to the old record. Reopening verifies the migration is not executed again.

Package contents and individual files

01Define the boundary

A new column changes the schema. The migration adds archived with a defined default. The test first creates the old database file and then opens it with the new schema. A fresh database would not cover this failure scenario.

lib/model.dart · dartOpen file
import 'dart:io';
import 'package:drift/drift.dart';
import 'package:drift/native.dart';

class VehicleDb extends GeneratedDatabase {
  VehicleDb(File file, this.version) : super(NativeDatabase(file));
  final int version;
  @override
  int get schemaVersion => version;
  @override
  Iterable<TableInfo> get allTables => const [];
  @override
  MigrationStrategy get migration => MigrationStrategy(
    onCreate: (_) async {
      await customStatement(
        'CREATE TABLE vehicles(id INTEGER PRIMARY KEY, name TEXT NOT NULL)',
      );
      if (version >= 2) await addArchived();
    },
    onUpgrade: (_, from, to) async {
      if (from < 2 && to >= 2) await addArchived();
    },
  );
  Future<void> addArchived() => customStatement(
    'ALTER TABLE vehicles ADD COLUMN archived INTEGER NOT NULL DEFAULT 0',
  );
  Future<void> insert(String name) =>
      customStatement('INSERT INTO vehicles(name) VALUES (?)', [name]);
  Future<List<QueryRow>> rows() =>
      customSelect('SELECT * FROM vehicles ORDER BY id').get();
}

02Set up the learning project

Direct dependencies are pinned. Extract all files together and run flutter pub get. Do not use an existing app database for tests. Tests create and clean up their own data.

pubspec.yaml · yamlOpen file
name: learning_example
publish_to: none
environment:
  sdk: ">=3.11.0 <4.0.0"
dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: 3.3.1
  drift: 2.33.0
  path_provider: 2.1.5
dev_dependencies:
  flutter_test:
    sdk: flutter
flutter:
  uses-material-design: true

03Trace the successful outcome

Check that old names survive, archived receives its default and reopening needs no second upgrade. Deleting the file would not test migration.

test/model_test.dart · dartOpen file
import 'dart:io';
import 'package:flutter_test/flutter_test.dart';
import 'package:learning_example/model.dart';

void main() {
  test('v1 data survives upgrade and reopening', () async {
    final directory = await Directory.systemTemp.createTemp('migration-');
    addTearDown(() => directory.delete(recursive: true));
    final file = File('${directory.path}/learning.sqlite');
    final old = VehicleDb(file, 1);
    await old.insert('Family car');
    await old.close();
    final upgraded = VehicleDb(file, 2);
    final rows = await upgraded.rows();
    expect(rows.single.read<String>('name'), 'Family car');
    expect(rows.single.read<int>('archived'), 0);
    await upgraded.close();
    final reopened = VehicleDb(file, 2);
    expect(await reopened.rows(), hasLength(1));
    await reopened.close();
  });
}

Run / check

flutter pub get
flutter test
Expected result

Check that old names survive, archived receives its default and reopening needs no second upgrade. Deleting the file would not test migration.

04Observe failures deliberately

Change an expected number or state in the test. flutter test must fail. Restore the correct expectation afterwards. Distinguish a domain failure from a missing plugin or development environment.

05Solve the extension

Additionally verify a fresh installation directly at version 2.

06Compare the solution

Fresh installation and upgrade must yield the same usable schema. The solution inserts into a new V2 file and then verifies archived. It does not replace the upgrade test.

Expected result

flutter test passes for the original example and the extended solution.

Your exercise

Additionally verify a fresh installation directly at version 2.

Show the solution and explanation

Fresh installation and upgrade must yield the same usable schema. The solution inserts into a new V2 file and then verifies archived. It does not replace the upgrade test.

solution/model_test.dart · dartOpen file
import 'dart:io';
import 'package:flutter_test/flutter_test.dart';
import 'package:learning_example/model.dart';

void main() {
  test('fresh v2', () async {
    final dir = await Directory.systemTemp.createTemp('fresh-');
    final db = VehicleDb(File('${dir.path}/new.sqlite'), 2);
    try {
      await db.insert('New');
      expect((await db.rows()).single.read<int>('archived'), 0);
    } finally {
      await db.close();
      await dir.delete(recursive: true);
    }
  });
  test('v1 data survives upgrade and reopening', () async {
    final directory = await Directory.systemTemp.createTemp('migration-');
    addTearDown(() => directory.delete(recursive: true));
    final file = File('${directory.path}/learning.sqlite');
    final old = VehicleDb(file, 1);
    await old.insert('Family car');
    await old.close();
    final upgraded = VehicleDb(file, 2);
    final rows = await upgraded.rows();
    expect(rows.single.read<String>('name'), 'Family car');
    expect(rows.single.read<int>('archived'), 0);
    await upgraded.close();
    final reopened = VehicleDb(file, 2);
    expect(await reopened.rows(), hasLength(1));
    await reopened.close();
  });
}

Project context and sources

This independent learning project explores a topic in this technology area. Project references provide a pinned revision as architectural context. They do not imply that every library or feature introduced here is already used in that application.