Drift Schema Migrations: Evolving Your Database Safely

Why it exists

When you ship an app, users have a database with a specific structure, or schema. If you update the app and change that structure (e.g., add a user_bio column), the app will crash for existing users unless you provide instructions on how to migrate their old database to the new schema. Schema migrations are those instructions, ensuring updates don't break the app for your existing user base.

The mental model

A schema migration is like the instructions in a flat-pack furniture box. Your app knows how to build the database from scratch (the final picture), but for users who have an older version, it needs a step-by-step guide to transform what they have into the new design without throwing away all the contents. Drift's make-migrations tool is a service that compares your old and new database designs and pre-writes most of these instructions for you.

How it works

First, you configure your build.yaml to point to your database file. You run dart run drift_dev make-migrations to save a snapshot of your current schema. Then, you modify your Dart table definitions. After your changes, you must increment the schemaVersion integer in your database class and run make-migrations again. This prompts Drift to compare the new schema with the old one and generate a .steps.dart file. You use the helpers in this file, like stepByStep, inside your database's MigrationStrategy to define the upgrade logic, such as m.createTable(...) or m.addColumn(...).

When to use it

Use migrations for any change to your database schema after your app's initial release. This includes adding, renaming, or removing tables or columns, or changing column constraints. It's a mandatory practice for any production Flutter or Dart app using Drift to ensure smooth updates. The make-migrations command is the recommended, tool-assisted approach.

When not to use it

During very early development before any users have the app, you might find it faster to just clear app data and start fresh instead of writing a migration for every small tweak. However, as soon as your app is in the hands of testers or users, you must use migrations. Migrations are for schema changes, not for modifying application data (e.g., correcting a typo in a user's name); use regular update statements for that.

One canonical example

After adding a groups table to your Dart code, you bump schemaVersion from 1 to 2 in your MyDatabase class and run make-migrations. Drift generates a helper. You then implement the onUpgrade strategy: MigrationStrategy(onUpgrade: stepByStep(from1To2: (m, schema) async { await m.createTable(schema.groups); })). Here, m is the Migrator that executes commands, and schema is a type-safe representation of the tables as they exist in version 2, letting you create the new table correctly.