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.
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.
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.
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 testCheck 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.
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.
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.