聊数据库迁移这事儿，我第一个想到的就是搬家——不是那种叫个搬家公司、一车拉走就完事的轻松活儿，而是那种老房子里堆了几十年的旧家具、破箱子、还有不知道从哪儿冒出来的蜘蛛网。你看着文档上写的“迁移方案”四个字，觉得挺简单，但真上手了，第一关就是怎么把这些文件、配置、脚本整理明白。
我见过太多团队，一上来就急着写迁移计划，结果连源库的表结构都没搞清楚。有个朋友跟我吐槽，他们公司迁移 Oracle 到 MySQL，文档里列了 200 张表，实际跑起来却少记了 50 张，原因是 DBA 偷懒，只把“看起来能用”的表列进去了。这事儿听着荒唐，却并不少见。数据库迁移文档不是写给别人看的，而是给自己用的——它得像张活地图，标清楚每个坑在哪儿、每条路怎么绕过去。写的时候要想，三个月后你自己回来看，能不能一眼看懂。
说到文档怎么写，我建议分三层：第一层是“干什么”，比如迁移目标、源库和目标库的版本、架构图；第二层是“怎么干”，包括迁移步骤、脚本、工具选择；第三层是“出错了怎么办”，比如回滚方案、验证脚本、监控指标。很多人只写前两层，觉得第三层没必要，但恰恰是那些“万一”的情况，最能检验文档的质量。我有个同事，当年迁移 MySQL 到 TiDB，文档写得漂亮，步骤全对，结果迁移到一半发现字符集不兼容，出现一堆乱码。因为没有准备回滚方案，整整折腾了两天。从那以后，他写文档的第一件事就是写回滚步骤。
工具选择这块也是个大坑。市面上迁移工具多得很，像 AWS 的 DMS、阿里云的 DTS、开源的 DataX、Kettle，各有各的脾气。但很多人写文档时，只写“用工具 A 迁移”，不写为什么要用 A。我见过一个案例，团队用 DataX 迁移 PG 到 MySQL，文档里只说“配置好连接”，结果因为 DataX 默认单线程，几十 GB 的数据跑了三天三夜。后来改成多线程配置，半天搞定。问题出在文档没写清楚工具的局限性。写迁移文档时，一定要备注工具的优缺点，比如“DataX 适合全量迁移，但增量同步需配合 Canal”，省得后面的人踩同样的坑。
数据校验这块，很多人以为是事后的事儿，其实应该贯穿整个迁移流程。我有个朋友在金融行业，他们迁移核心交易库，文档里写了个“校验脚本”，但只在迁移完成后跑一次。结果迁移完发现，有几张表的数据量对得上，却字段值不一致——因为源库有触发器，迁移时没停掉。这教训太深刻。好的迁移文档会写清楚“什么时候跑校验脚本”“校验哪些维度”“如果校验不一致，怎么定位问题”。比如：迁移前跑一次源库的 count(*) 和 checksum，迁移中每 10 万条记录抽样对比，迁移后全量跑一致性校验。这样即使出问题，也能快速缩小范围。
还有一个容易被忽视的细节：权限和账号管理。我见过一个案例，团队迁移完数据库，业务方反馈说“连不上”。查了半天，发现目标库的账号权限没配好，只给了 SELECT，没给 INSERT。这在文档里本该写成一句话：“迁移后，需在目标库创建与原库一致的账号，并授权对应权限”。但很多人觉得这是常识，就懒得写。结果新来的运维照着文档操作，卡在权限上，一脸懵。写文档时，别假设读者懂你的潜台词。你越觉得理所当然的东西，越要写清楚，包括端口号、IP 白名单、SSL 配置这些细节。
聊聊文档的版本管理。数据库迁移不是一次性的事儿，往往要反复迭代。我有个朋友，他们公司做跨机房迁移，前后改了四版方案。第一版是“全量+增量”，第二版改成“双写+校验”，第三版又加了“灰度切换”。但文档没人维护，新来的同事一看，还以为是第一版，结果迁移当天照着旧方案操作，差点出事故。这让我明白，迁移文档得活起来——不是写完就扔 GitHub 吃灰，而是每次变更方案、发现新坑，都要及时更新。可以设个“变更日志”，记录每次改动的原因和时间，这样后面的人才能知道哪一步是踩过坑的，哪一步是优化的。
说到底，数据库迁移文档不是技术报告，而是一本“避坑指南”。它不需要花里胡哨的排版，也不需要高大上的术语，只要把真实踩过的坑、试过的方案、验证过的脚本老老实实写下来。这样，下次有人遇到类似问题，翻开文档就能少走很多弯路。毕竟，数据库迁移这事儿，成也文档，败也文档。
