Improve documentation for first step-by-step migration

[goerlitz]

I've implemented my first migration using the step-by-step approach but I encountered several obstacles.

This is a summarization of my experience and some recommendations how to improve the documentation to make it easier for everyone.

First of all, I followed the Getting Started document closely.

Drift offers an all-in-one command for writing and testing migrations.

This is great!!! But first wrong assumption: the all-in-one command does everything for me. 🔥

I followed the steps:

1. "Add the location of your database(s) to your build.yaml file." ✅
2. "Generate the initial schema file" (dart run drift_dev make-migrations) ✅
3. "Once this initial schema file is saved, you can start making changes to your database schema." ✅
4. "Bump the schemaVersion in your database class" ✅
5. "run the command again" (dart run drift_dev make-migrations) ✅

A step-by-step migration file will be generated next to your database class. Use this function to write your migrations incrementally. See the step-by-step migration guide for more information.

Huh? Write my migrations incrementally? How? 🤔

There is:

• a link to https://drift.simonbinder.eu/Migrations/step_by_step/
• an example just below
• a link to an example in the drift repository
• an example in the output of the make-migrations command:

It turns out that the example in the make-migrations command would is best to go ahead, but I got lost in the examples given in the documentation before I figured this out. 🙁

👉 A first example for the step-by-step migration should actually be shown on the Getting Started page instead of other pages that cover much more ground.

@DriftDatabase()
class Database extends _$Database {
  // Constructor and other methods

  MigrationStrategy get migration {
    return MigrationStrategy(
      onUpgrade: stepByStep(
        from1To2: (m, schema) async {
          await m.addColumn(schema.users, schema.users.birthdate);
        },
      ),
    );
  }
}

However, there are still two issues:

• import 'database.steps.dart'; is missing
• @override annotation is missing for the getter

And another issue: I had to change
AppDatabase() : super(_openConnection());
to
AppDatabase([QueryExecutor? e]) : super(e ?? _openConnection());

Luckily, this was mentioned in the output of make-migrations command.

Finally, the make-migrations command recommended to run the generated tests with flutter test test/drift/app_database/migration_test.dart.
Again, the documentation does not cover this in the getting started section.

And last but not least...

• the General tips look great, but it is not clear how to combine them with the step-by-step migration.
• step-by-step migrations do not support m.dropColumn() in a type-safe way, because only the new schema is passed as parameter.

TL;TR

The Getting Started documentation is great but not clear enough on all steps for doing your first step-by-step migration.

Other people also had problems with doing this start-to-end, e.g. here and here.

I'd recommend that the Getting Started page is improved such that each step for doing the first step-by-step migration is clearly listed, e.g.

1. "Add the location of your database(s) to your build.yaml file."
2. "Generate the initial schema file" (dart run drift_dev make-migrations)
3. "Once this initial schema file is saved, you can start making changes to your database schema."
4. "Bump the schemaVersion in your database class"
5. "run the command again" (dart run drift_dev make-migrations) and follow advices given in the output.
6. Write your own migrations. See example here ...
7. Run generated test: flutter test test/drift/app_database/migration_test.dart.

[dickermoshe]

This is great!!! But first wrong assumption: the all-in-one command does everything for me. 🔥

make-migrations sounds like it actually writes the migrations. I really wish we have picked a better name, but I really could not come up with anything better at the time. I'm willing to use another name.

And another issue: I had to change
AppDatabase() : super(_openConnection());
to
AppDatabase([QueryExecutor? e]) : super(e ?? _openConnection());

This recommendation was updated recently to account for this. However for old users, we should add this to the docs/command line output/ warn the user if the constructor doesn't match.

It turns out that the example in the make-migrations command would is best to go ahead, but I got lost in the examples given in the documentation before I figured this out. 🙁

Good point. At example of actualy migrations should be on this page. Also, testing should be on this page too!

the General tips look great, but it is not clear how to combine them with the step-by-step migration.

These were writen waay before make-migrations existed. Agree.

step-by-step migrations do not support m.dropColumn() in a type-safe way, because only the new schema is passed as parameter.

@simolus3 how did we miss this? What are users to do?

import 'database.steps.dart'; is missing
@override annotation is missing for the getter

Good point. These should be added to

---

This is clearly an issue. Gonna try to make time for it.

[goerlitz]

I think make-migrations is a great tool. I removes a lot of hassle and writing boilerplate code.
The documentation just needs more clarity and better expectation management.

When reading the docs I often felt like reading "This is what you can do ...". But as a noob in migrations I'm rather lost between the different examples - I rather wanted to know "what I should do" when using the step-by-step migration.

A dedicated stepwise dot-point list from start (initial schema generation) to end (testing) for step-by-step migrations would be highly beneficial.

as for the m.dropColumn(), I just put in the column name as String - it works, but it is not "type-safe" ;)