Drift数据库迁移中多次修改同一表的问题解析

问题背景

在使用Drift数据库时，开发者可能会遇到一个常见的迁移问题：当对同一个表进行多次修改时，直接跨版本升级会导致迁移失败。这种情况特别容易出现在需要逐步添加多个字段的场景中。

问题复现

假设我们有一个名为Box的表，迁移需求如下：

1. 在版本2中，添加refferenceId字段并设为唯一键
2. 在版本3中，添加refferenceNumber字段并设为唯一键

当应用从版本1逐步升级到版本2再到版本3时，迁移工作正常。但如果直接从版本1升级到版本3，就会出现"no such column: refference_number"的错误。

问题根源

这个问题的本质在于迁移逻辑的执行方式。当直接跨版本升级时，迁移处理器会执行所有小于目标版本的迁移条件块。在示例中，从版本1到版本3的升级会同时触发版本2和版本3的修改，导致对同一个表执行两次alterTable操作。

解决方案

方案一：合并迁移逻辑

最直接的解决方案是在每个迁移条件块中完成所有必要的修改：

if (from < 2) {
  await m.alterTable(
    TableMigration(
      box,
      newColumns: [box.refferenceId, box.refferenceNumber],
    ),
  );
} else if (from < 3) {
  await m.alterTable(
    TableMigration(
      box,
      newColumns: [box.refferenceNumber],
    ),
  );
}

这种方法虽然可行，但随着版本增多会变得难以维护。

方案二：使用分步迁移

Drift提供了更优雅的分步迁移方案，通过生成中间版本的数据库模式来实现真正的逐步迁移：

1. 首先需要导出旧版本的数据库模式
2. 使用Drift提供的工具生成中间版本
3. 编写分步迁移逻辑

onUpgrade: stepByStep(
  from1To2: (m, schema) async {
    await m.alterTable(schema.box, newColumns: [schema.box.refferenceId]);
  },
  from2To3: (m, schema) async {
    await m.alterTable(schema.box, newColumns: [schema.box.refferenceNumber]);
  },
),

最佳实践建议

1. 规划迁移策略：在设计数据库变更时，预先考虑可能的跨版本升级场景
2. 保持迁移原子性：每个迁移步骤应该独立完成，不依赖后续步骤
3. 使用分步迁移：对于复杂的数据库变更，优先考虑使用Drift的分步迁移功能
4. 测试覆盖：确保测试包含逐步升级和直接跨版本升级两种场景

总结

Drift数据库的迁移功能虽然强大，但在处理同一表的多次修改时需要特别注意。理解迁移执行的内部机制，合理规划迁移策略，可以有效避免这类问题。对于长期维护的项目，采用分步迁移方案能够提供更好的可维护性和可靠性。