数据库迁移与版本升级

【踩坑实录】数据库迁移与版本升级

▍现象
电子书管理工程的元数据体系：上游用嵌入式数据库存书库元数据（书名、标签、阅读进度），数据库结构随上游版本演进（加表、加列、改索引）。移植版第一次跟上遊大版本升级时撞上迁移问题：新版代码读旧版数据库，迁移逻辑要跑，而迁移逻辑的路径假设在沙箱里变了——数据库文件的位置与权限上下文都是新的。

▍定位过程
数据迁移问题的排查要区分两层：迁移逻辑对不对（上游的迁移代码自身）、迁移环境对不对（文件路径、可写性、并发）。移植场景里第二层是高发区：路径映射错（迁移代码找不到库文件）、只读态（部署后未解锁写权限）、半升级态（迁移中断后重入）。工程的应对：升级路径的幂等设计（迁移可重复执行——中断后重跑不出错；这与工程的首启部署幂等解包同一套纪律）、迁移前备份（旧库整份备份，迁移失败可回滚重试）。

▍对策
四条纪律落地：一，版本号显式（库文件带结构版本，迁移按版本链逐级走——不假设从任意版本直接跳最新）。二，迁移事务化（结构变更与数据搬移在一个事务里，失败整体回滚）。三，升级场景的真机测试矩阵（覆盖安装升级是必测项——全新安装测不出迁移问题，这是移植工程最容易被漏的测试路径）。四，损坏兜底（迁移前的完整性校验、损坏库的重建路径——宁可重建索引不丢用户数据，书没了元数据可以重扫，数据文件本身不能碰）。

▍根因抽象
移动应用的升级频率远高于桌面（市场推送节奏），每次升级都是一次数据迁移考验。迁移质量 = 幂等性 + 事务性 + 测试矩阵 + 兜底，四件缺一不可。

▍方法论沉淀
发布前的升级演练：上一版本的真实数据（开发者自己用出来的库，不是造的数据）升级走一遍——真实数据的脏度（空字段、超长值、异常编码）是测试数据永远模拟不全的。

升级幂等与备份回滚的处置记录在电子书工程实录，apps 板块 56 篇欢迎对照。