关系库迁文档库:先做 id map,再谈 BSON 长什么样

关系库迁文档库:先做 id map,再谈 BSON 长什么样

Hello,我是小兔大白糖。 切文档库那天,最怕的不是 BSON 字段多几个,而是用户 A 的关注关系还指着旧库里的自增 ID,新库里却已经换了一套 _id——线上像断线的电路图。写成这篇,给要做关系库 → 文档库分阶段切流与身份映射调研的初中级后端同学:带走可复述的心智模型和选型清单,不是某次迁移工单的表名墙。

说明:下文模式与硬规则来自业界常见做法归纳,示例均为教学脱敏示意;不绑定某厂内部 runbook,也不把示意数字当真 SLA。

估计阅读时间:8 分钟


为什么现在要关心

跨存储迁移,贵的是「旧 ID 还能不能找到新 ID」和「按什么顺序搬」,不是文档 schema 长什么样。

关系库迁文档库(典型如 MySQL → MongoDB,也可换成 Postgres → 文档库)时,团队往往先纠结 ObjectId 还是 UUID、嵌套还是引用。真正拖垮进度、拖垮回滚信心的,通常是这四件事:

痛点不解决会怎样
旧自增 / 旧 UUID 与新 _id 如何双向找回边表、成员表端点解析失败,产生孤儿或静默丢数据
迁移顺序先迁边再迁点,或聚合先于主体,整批 quarantine
刻意不迁什么密码、设备、消息历史被「凑 schema」硬塞,切流后安全与体验双输
可重跑与验收断点脆弱、幂等缺失,重跑造出新 _id,旧 map 作废

若你已经在做存量回填(同库补洞、同管道重跑),那是另一条轴;本篇讲的是换存储时的身份换轨,二者正交,文末会链到回填文。


心智模型:搬家公司

把迁移想成搬家:映射表是旧门牌 → 新门牌通讯录;分 phase 是分批装箱;有些家具 deliberately 不搬。

legacy id 到 new id 的身份映射通讯录
legacy id 到 new id 的身份映射通讯录 · 点击查看 SVG 原图
搬家里的东西迁移里对应什么
旧门牌 → 新门牌通讯录身份映射表(id map):legacy_id → new_id(及业务唯一键)
先搬人、再搬关系、再搬房间成员依赖序:主体 → 边(关注)→ 依赖主体的聚合
到新家重新登记的家具不迁清单:设备令牌、密码哈希等,切流后由新路径创建

一句话:map 是换轨期的「地址真相」;phase 是拓扑序;不迁清单是产品与安全合同。

类比局限:搬家模型解释身份与顺序;解释不了双写窗口里 CDC、冲突合并、读路径灰度等全部细节——那些要叠加模式 C 或单独设计。


精确定义与边界

身份映射表:在切流窗口内,持久化「旧存储主键 / 业务键 → 新存储技术 _id」的映射;重跑、补批、解析边端点时以 map 为准,而不是每次重新 mint 新 id。

分阶段切流(phased cutover):按依赖拓扑分批加载数据,每批可断点、可幂等、可单独验收覆盖率;切流日再切换写路径(认证、设备等按 runbook 走新库或重建)。

不迁(rebuild on first use):旧表行与新文档模型无 1:1 对应时,不伪造行;切流后首次登录 / 首次使用时在新模型下创建。代价是切流日可能有体验断点,需产品接受。

与回填的关系:同库 historical backfill 解决「漏了补、可重跑」;跨库 id map 解决「换轨后旧键还能不能解析新键」。可以同时进行,但合同不同。


业界模式对照

教学基线选 B(显式 map + 分阶段负载);设备类无 1:1 旧行时叠加 D;高风险写路径可短期叠 C。

一把梭、id map、双写窗、热路径重建四种模式
一把梭、id map、双写窗、热路径重建四种模式 · 点击查看 SVG 原图
模式做法优点代价 / 副作用
A. 一次全表拷贝改 schemaETL 一把梭,切流日切换心理简单、项目计划短难回滚;ID 断裂后修成本高;大表一次失败面大
B. 显式 id map + 分阶段负载持久化 legacy→new;按依赖序批跑;边用 map 解析端点可重跑、可验收、可 quarantine要维护 map 存储与运维;边迁移多一轮「查 map」
C. 双写窗口新旧库并行写一段时间,再收旧写切流相对平滑;读可灰度双写一致性、冲突策略、监控复杂度高;窗口拖长成本涨
D. 只迁冷数据,热路径重建历史只读迁;设备 / 会话登录等切流后重建降低错迁、错配 secret 的风险切流日体验断点;需明确「哪些集合不迁」
B + D(常见组合)用户与关系走 map + phase;设备走首次登录重建平衡可验收与安全产品要接受「重新登录 / 重新绑设备」
B + 短期 C(高风险写)核心写双写数天,读仍可按 map 校验写路径切换更稳双写 bug 可能两边脏;要有明确关窗条件

没有「零代价最佳实践」:B 的 map 是运维资产;C 的平滑是用复杂度换的;D 的安全是用切流日体验换的。


硬规则(六条)

1. 先定业务唯一键,再定技术 _id。

例如规范化手机号、租户内唯一 username——写入 map 时同时保留「业务键 ↔ legacy ↔ new」,便于对账与客服查人。只记自增 ID、业务键漂移后,map 会对不齐。

2. 依赖序写死:主体 → 边 → 依赖主体的聚合。

典型序:用户 → 关注关系 → 房间与成员。边迁移时用 map 解析两端;禁止在边批里「猜」新 id 或临时 hash 凑端点。

3. map 是真相:重跑必须复用已映射的 new_id。

幂等语义:同一 legacy_id 再次进入管道,应得到同一 new_id。每次重跑重新生成 ObjectId,会造孤儿文档、重复用户、关注指向错误对象——比慢更致命。

4. 显式「不迁清单」写进切流 runbook。

密码哈希、OAuth 绑定、设备指纹、消息正文等,按安全与产品合同列清单:不迁或切流后重建。清单外的「为了凑齐 schema 伪造一行」是事故预备役。

5. 验收看覆盖率,失败进 quarantine,别静默吞。

边的两端是否都在 map 里;无法解析的行进隔离区(quarantine),带原因码,可重放。整批失败或整批跳过不可解析行,都会在切流后以不同方式爆炸。

6. 断点按实体 / phase,别只靠 OFFSET 当唯一进度。

大表 LIMIT/OFFSET 进度在数据变更、索引选择下脆弱;与 存量回填 vs 增量管道 里强调的一样,更稳的是按主键游标、按 phase、按实体类型的 checkpoint。跨库迁移同样适用。


示意:分 phase 顺序(教学)

全文只保留一段伪流程,便于贴进评审幻灯片;具体表名、批大小、并行度按你的库定。

主体到边到聚合再到切流的依赖序
主体到边到聚合再到切流的依赖序 · 点击查看 SVG 原图
phase1: users + id_map(写入 legacy → new,固化业务唯一键)
phase2: follows(边端点经 map 解析;失败 → quarantine)
phase3: rooms + members(成员引用 user 的 new_id)
cutover: 认证写新库;设备 / 令牌走「首次登录重建」(不迁清单)
验收: map 覆盖率、边双端命中率、quarantine 可重放量

切流日写路径切换与读灰度,不在此段展开;若叠加双写,建议在 phase 稳定后再开 C 窗口,避免「边还没迁完就开始双写关注」。


反模式

下面四条在架构评审里应直接亮红灯。

反模式为什么危险
边迁移时现场「猜」新 id 或临时映射不可重跑、不可对账;重跑后图结构静默变化
伪造设备 / 令牌行以凑齐文档 schemasecret 与指纹不应复制进新模型;安全与合规风险
消息历史与元数据绑死同一次迁体量与一致性模型不同;失败面绑在一起,回滚难
无 quarantine:解析失败则整批失败或整批吞前者阻塞切流;后者上线后才发现缺边、缺成员

选型结论

有图状依赖(用户—关系—房间)→ 优先 B + 依赖序;新模型与旧行不对齐 → D(不迁 + 首次使用重建);写路径极敏感 → 短期 C,但要有明确关窗与对账。

可行动清单(转发给同事时复述这几条即可):

  1. 先上 map 与 phase 合同,再争论 BSON 嵌几层——没有 map,后面每一批边都在赌。
  2. 业务唯一键与 legacy、new 三元组进 map,验收按覆盖率与 quarantine,不靠「跑完没报错」。
  3. 不迁清单与产品、安全一起签字,设备类默认 D,别 ETL 硬搬。
  4. 断点与幂等按实体 / phase,与存量回填同一套进度哲学;详见 存量回填 vs 增量管道。
  5. 模式 A 只适合极小、可接受不可逆的数据集;生产级社交 / IM 元数据,业界更常见 B(必要时 +D / 短期 C)。

跨存储切流做完,同库里的漏迁、补洞仍可能继续——那是回填与增量管道要解决的问题,不是本篇 map 能替代的。把「换轨」和「补洞」分两篇文章、两个 runbook,团队会少踩一半混概念的低级坑。