NoSQL 与搜索 / 系统课时

实施 Schema 版本化与在线迁移

实施 Schema 版本化与在线迁移

在线 Schema 迁移的目标不是“尽快把旧文档改完”,而是让新旧格式在一段时间内同时可用。本课用 schemaVersion、兼容读写、后台回填和最终收口组成迁移链路,避免一次性停机重写整个集合。

学习目标

  • 能用 schemaVersion 明确区分文档结构版本
  • 能设计兼容读写与后台回填的迁移顺序
  • 能验证旧版数据清零后再安全移除兼容代码

先定义版本边界

假设旧版用户文档把城市直接存为 city,新版要改成 address.city。不要仅靠“字段是否存在”猜版本,而应给新写入的数据显式记录 schemaVersion: 2。这样读取、回填和审计都能基于稳定条件判断。

迁移期间通常采用“先兼容、再回填、最后收口”的顺序:先发布能读 v1/v2 的代码,再让新写入进入 v2,随后后台批量回填 v1,确认没有旧文档后才删除旧字段与兼容分支。

Schema 在线迁移从兼容窗口到收口的流程

让应用先兼容新旧格式

下面是 TypeScript 片段示例,假设数据库访问层已经得到一个用户文档。读取函数同时接受 v1 和 v2;写入函数在兼容窗口内写入 v2 字段,并保留旧 city 字段,方便旧版本应用尚未完全下线时继续工作。

ts
type UserDoc = {
  _id: string;
  schemaVersion?: 1 | 2;
  city?: string;
  address?: { city: string };
};

function readCity(user: UserDoc): string | undefined {
  if (user.schemaVersion === 2) {
    return user.address?.city;
  }
  return user.city;
}

function buildCityUpdate(city: string) {
  return {
    $set: {
      schemaVersion: 2,
      "address.city": city,
      city
    }
  };
}

这是片段示例,依赖你的 MongoDB Repository 或 Driver 调用上下文。其生效行为是:新版本读取两种结构,新版本写入时以 v2 为主,同时暂时维持旧字段;旧应用全部下线后才能停止这段双写。

分批回填旧文档

后台回填要做到可重复执行。下面的 mongosh 示例只处理仍为 v1 或没有版本号、且存在 city 的文档;更新使用管道把旧值复制到新结构,再标记为 v2。

javascript
db.users.updateMany(
  {
    $or: [
      { schemaVersion: 1 },
      { schemaVersion: { $exists: false } }
    ],
    city: { $exists: true }
  },
  [
    {
      $set: {
        schemaVersion: 2,
        address: {
          $mergeObjects: [
            { $ifNull: ["$address", {}] },
            { city: "$city" }
          ]
        }
      }
    }
  ]
)

db.users.countDocuments({
  $or: [
    { schemaVersion: 1 },
    { schemaVersion: { $exists: false } }
  ]
})

预期输出

text
0

updateMany() 本身还会返回匹配数与修改数,具体数值取决于当前数据量;这里真正的验收条件是第二条查询返回 0。生产环境应按 _id 范围或时间窗口分批执行,而不是一次更新数百万文档。

用监控决定何时收口

不要在“回填脚本跑完”这一刻立即删除兼容逻辑。至少要同时检查 v1 剩余数量、读取旧分支命中次数、写入错误率以及回填失败记录。只有 v1 数量持续为 0,旧应用已经下线,并经过约定的观察窗口,才进入收口。

收口时先停止双写旧 city,保持读取兼容一小段时间;确认没有旧字段依赖后,再删除旧读取分支,并通过第二次后台清理移除冗余 city 字段。这种两阶段删除比“一次发布同时删读、删写、删数据”更容易回滚,也更容易定位问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实施 Schema 版本化与在线迁移

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通