Drift数据库迁移中的常见陷阱与最佳实践

迁移问题的本质

在数据库迁移过程中，开发者经常会遇到各种意外情况，特别是当应用版本跨度较大时。Drift作为一个强大的Flutter数据库工具，虽然提供了灵活的迁移机制，但也存在一些需要特别注意的陷阱。

典型问题场景

一个典型的迁移错误出现在以下情况：开发者需要执行多个迁移步骤，比如先修改表结构再添加新列。当用户直接从旧版本升级到最新版本时，迁移代码会依次执行所有必要的变更。

问题核心在于alterTable操作的本质。每次调用alterTable时，Drift会在底层创建一个临时表，复制数据，然后替换原表。如果在同一个迁移过程中对同一个表多次调用alterTable（包括间接调用，如通过addColumn），就会导致数据复制时引用不存在的列。

问题重现示例

考虑以下迁移代码：

onUpgrade: (Migrator m, int from, int to) async {
  if (from < 2) {
    // 修改title字段为可空
    await m.alterTable(TableMigration(todoItems));
  }

  if (from < 3) {
    await m.addColumn(todoItems, todoItems.updatedAt);
  }
}

当用户从版本1直接升级到版本3时，会先执行表结构修改，然后尝试添加新列。由于addColumn内部也使用了alterTable，这实际上是对同一个表进行了两次结构变更操作，导致SQLite抛出"no such column"错误。

解决方案

1. 使用分步迁移

Drift推荐使用"step-by-step"迁移方式，这是最安全可靠的解决方案。这种方式要求为每个版本单独定义迁移逻辑，确保每次只执行一个版本的变更。

迁移到分步迁移模式非常简单：

1. 将现有数据库版本号增加1
2. 在onUpgrade中为每个中间版本添加迁移逻辑
3. 确保每个版本变更都是独立的

2. 手动迁移时的注意事项

如果必须使用手动迁移方式，需要注意：

• 避免对同一个表多次调用alterTable
• 特别注意addColumn等便捷方法内部也使用了alterTable
• 考虑将多个变更合并到单个alterTable调用中

测试的重要性

无论采用哪种迁移方式，充分测试都是必不可少的。应该测试以下场景：

1. 全新安装最新版本
2. 从每个历史版本逐步升级到最新版
3. 从最旧版本直接跳到最新版
4. 各种中间版本的升级路径

Drift提供了良好的测试支持，可以轻松验证迁移是否按预期工作。

最佳实践总结

1. 优先使用分步迁移：这是Drift推荐的方式，能避免大多数迁移问题
2. 全面测试：覆盖各种升级路径，特别是大版本跨越的情况
3. 谨慎使用手动迁移：如果必须使用，确保理解底层机制
4. 逐步应用变更：每个版本只做最小必要的变更
5. 文档记录：为每个迁移变更添加注释，说明目的和影响

通过遵循这些最佳实践，可以显著降低数据库迁移过程中出现问题的风险，确保用户数据安全平稳地过渡到新版本。