A guide to migration in flutter with Moor

A quick guide on how to write migration for moor database

Running database migration can be a very daunting and delicate task considering that any mistake you make could make your users come for your head, However Moor presents a more developer friendly way for performing migration without breaking things or requesting that previous version of you app be uninstalled.

What is Migration

Migration is like a conflict resolution strategy to bring the old database up to speed on the new changes so it can be seamlessly updated without losing user’s sensitive data. — Me

When you have an existing app with a database of 1 table, and you make changes to that table, lets say you create an entirely new table, the old version of you app does not know that, when you try yo update the app with the new database schema there will be conflict between the old database schema (structure) and the new database schema (Structure), so essentially migration is like a conflict resolution strategy to bring the old database up to speed on the new changes so it can be seamlessly updated without losing user’s sensitive data.

What could happend without migration.

When you change your database schema (Structures of table and columns) without changing the database version — your app will crash.

If you change the schema and database version without providing a migration strategy — your app will crash giving your users a terrible user experience.

To avoid all this we have to understand how migration works in moor and how we can carefully implement it in our app.

How Moor Migration API works

Moor provides a migration API that can be used to gradually apply schema changes after bumping the schemaVersion getter inside the Database class. To use it, override the migration getter. Here’s an example: Let’s say you wanted to add a due date to your todo entries — Moor documentation

Lets now diffuse all this grammar:

When ever you make changes to the schema of your database, changes like :

• Adding a new column to an existing table
• Adding a new table
• Change the data type of a column within the table

You database schema has changed and you must increase your database version.

But increasing your database version is clearly not enough, you have to explain to your app how such changes will be implemented. It’s okay if you don’t totally understand we talk about how to go about in a few sec.

Here is a typical database class in flutter :

1. A table

2. A database class

Currently our schemaversion(Database version) is its default version — version 1.

We have no migration strategy implemented. Now lets move a few things around.

Adding a new column to the NotesDB Table.

Now we have a new column in out Notes table which means we have to make changes in two places in our database class:

1. schemaVersion
2. Migration

Our new database class will look like this:

From: This is the database version currently running on the app before the upgrade, ours will be 1.

Before the database is built the onUpgrade version is called and migration needed is done to avoid crash, Then the database will open.

If you change database schema and schema version without providing migration, you app might crash and result in loss of data depending on the circumstances.

Adding a new Table to the database

Adding a new table to the database and running migration is just as straight forward as adding a new column.

Lets say we add a new table called Todo

Our database class will be modified as such

We can see that we have to add another migration to our migration strategy to handle migrations from version 2 to version 3.

More complex Migrations

Some other migrations are quite complex and must be done with understanding and care. such as :

• Changing the data type of the column
• Renaming a column
• Changing the constraints of the column (Nullable to nonNullable)

We will try to do these three changes using the same example as before

what we want to do

• In the NotedDB table change “category” column name to “category_id” (Let’s assume this column has always contained the ID of the category rather than its name)
• Change the column Data-type of the “category” column from TextColumn to IntColumn
• Make the date column a Nullable field

Our new NoteDB class will look like this

Date column is now nullable

Category column is now category_id and to contain

How ever be careful when casting columns to another data type bcus all item in the column will be casted to the new type specified, and you dont want any TypeCaseErrors.

our database class will look like this.

Now we have changed our database schemaVersion to version 4 and written necessary migration steps so we don’t have any issue seamlessly migrating to a new version of you app.

Conclusion

We have learned a great deal about migrations in flutter with moor database and how to manage changes in database schema and more importantly the perils in not implementing migrations.

Thanks for reading and give it a clap if you leant a thing or two.

Lets say we add a new table called Todo

our table looks like this: