跳到主要内容

Schema 迁移

当实体结构发生变化（新增字段、重命名、数据回填）时，通过 RxDB 的 迁移脚本 机制在数据库连接前执行一次性数据变更。

迁移机制​

迁移脚本在 RxDB 配置的 migrations 数组中声明，每条迁移实现 MigrationType：

interface MigrationType {
  name: string; // 唯一名称，按名称字典序排序执行
  up(): Promise<void>; // 正向迁移
  down(): Promise<void>; // 回滚（预留）
}

执行规则：

  1. 迁移在数据库连接阶段自动运行（建表之后）。
  2. 按 name 字典序排序执行 —— 建议用 0001-、0002- 前缀保证顺序。
  3. 已执行的迁移记录在内建的 rxdb_migration 表中，不会重复执行。
  4. 某条迁移 up() 抛错会记录错误并中断，修复后重连继续。

声明迁移​

import { RxDB } from '@aiao/rxdb';
import { firstValueFrom } from 'rxjs';

const db = new RxDB({
  dbName: 'myapp',
  entities: [Todo],
  migrations: [
    {
      name: '0001-backfill-todo-completed',
      async up() {
        // 1. 查询历史数据
        const todos = await firstValueFrom(Todo.find({}));

        // 2. 回填：把缺失的 completed 字段补为 false
        for (const todo of todos) {
          if (todo.completed === undefined) {
            todo.completed = false;
            await todo.save();
          }
        }
      },
      async down() {
        // 预留：如需回滚在此实现
      }
    }
  ]
});

await db.connect('sqlite');

命名与顺序建议​

  • 用零填充的数字前缀（0001-、0002-）保证字典序即执行序。
  • name 一旦发布不要修改 —— 改名会被视为新迁移而重复执行。
  • 每条迁移保持幂等友好：即使部分执行过也能安全重跑。

注意事项​

  1. 迁移在建表之后、应用查询之前运行，此时可安全读写实体仓库。
  2. 迁移记录持久化在本地库中，卸载/清空数据库会重置迁移历史。
  3. 复杂结构变更（重命名字段、拆表）建议：新增字段 → 回填 → 逐步淘汰旧字段，分多条迁移完成。

参考​