Flutter 使用 ORM 框架管理数据库版本迁移

前言

我们前面一篇介绍了使用 floor 这个 ORM 框架处理 Flutter 本地的 SQLite 数据库。使用 ORM 框架最大的好处是简化了数据库维护的代码量，使得我们可以专注于业务代码实现。在之前，我们也讲到了不同 App 版本的数据表结构变化后，如何使用 sqflite 来处理版本升级。本篇，我们看看使用 floor 如何处理数据库版本升级。

floor 数据库版本升级

floor 框架同样提供了数据库版本号，当前使用的版本号使用注解配置。

@Database(version: 1, entities: [Memo])

当数据表结构发生变化时，就需要变更版本号指定新的版本。同时需要做如下处理：

更新实体类：比如增加或减少字段，变更字段类型等等；
编写迁移处理Migration类对象，Migration 类定义如下：

Migration(this.startVersion, this.endVersion, this.migrate)

其中第一个参数为起始版本号，第二个参数为要迁移到的版本号，最后是一个迁移处理函数，函数定义为：Future<void> Function(sqflite.Database database) migrate。我们要做的数据表变动就在这个函数里处理。

将编写好的Migration类对象添加到数据库初始化的 addMigrations 方法中，addMigrations方法接收一个Migration对象数组，因此是支持多种迁移的，比如从版本1迁移到版本3的迁移对象，从版本2迁移到版本3的迁移对象，从而满足多个版本同时迁移。

final database = await $FloorAppDatabase
    .databaseBuilder('app_database.db')
    .addMigrations([migration1to3, migration2to3])
    .build();

实体类变更后，需要用代码生成命令重新生成数据库操作的相关代码。

看起来非常简单，我们来看实际的例子。

版本升级实例

我们给之前的备忘录增加一个分类（category）字段，可以设置备忘录的分类，分类我们简单地固定为预设的几类。我们按照上面的步骤一步步编写代码即可。

变更版本：将数据库版本号改为2；

@Database(version: 2, entities: [Memo])

在备忘录类增加分类字段，由于已有数据的分类字段是 null 的，因此需要设置这个字段可为空Nullable；设置为非空也可以，只是需要在迁移时给旧版本已有数据相应字段设置非空初始值。

@entity
class Memo {
  @PrimaryKey(autoGenerate: true)
  final int? id;
  String title;
  String content;
  @ColumnInfo(name: 'created_time')
  DateTime createdTime;
  @ColumnInfo(name: 'modified_time')
  DateTime modifiedTime;
  String? category;
  List<String> tags;

  Memo({
    this.id,
    required this.title,
    required this.content,
    required this.createdTime,
    required this.modifiedTime,
    this.category = '',
    required this.tags,
  });
}

编写数据库迁移处理对象，并加入到版本迁移中。

final migration1to2 = Migration(1, 2, (database) async {
  await database.execute('ALTER TABLE Memo ADD COLUMN category TEXT');
  // 可选，设置旧版本字段初始值
  await database.update('Memo',{'category': ''});
});

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final database = await $FloorMemoDatabase
      .databaseBuilder('app_database.db')
      .addMigrations([migration1to2]).build();

  final dao = database.memoDao;

  getIt.registerSingleton<MemoDao>(dao, signalsReady: true);

  runApp(const MyApp());
}

运行下面的命令生成代码。

flutter packages pub run build_runner build

当然，我们也需要对 UI 相关的代码进行变更，变更后的 UI 界面如下图所示。备忘录.jpg 完整代码已经提交到：本地存储相关代码。

总结

从代码量上来说，使用 floor 和直接使用 sqflite 处理版本迁移差不多。相比直接使用 sqflite 做数据库版本迁移，使用 floor 的好处是可以通过添加多个 Migration 对象支持多版本迁移。

我是岛上码农，微信公众号同名。如有问题可以加本人微信交流，微信号：island-coder。

👍🏻：觉得有收获请点个赞鼓励一下！

🌟：收藏文章，方便回看哦！

💬：评论交流，互相进步！

本文正在参加「金石计划」