数据模型 Versioning 与迁移 — 应对应用升级的数据兼容性一、引言随着应用功能迭代数据库表结构不可避免需要变更——新增字段、修改字段类型、拆分表结构等。如果直接修改表结构而不考虑数据兼容性用户升级应用后将面临数据丢失或应用崩溃的风险。鸿蒙 RDB 提供了数据库版本管理和迁移机制允许开发者在版本升级时执行有序的数据迁移。MoneyTrack 在从个人记账到家庭记账的演进过程中通过合理的版本迁移策略实现了数据模型的无缝扩展。二、核心知识点2.1 数据库版本升级RDB 数据库通过version属性管理数据库版本号。每次创建或打开数据库时系统会比较当前版本号和期望版本号如果不一致则触发迁移流程constSTORE_CONFIG:StoreConfig{name:moneytrack.db,securityLevel:SecurityLevel.S1,version:3// 当前版本号}版本号从 1 开始递增每次表结构变更时将版本号加 1。版本号是正整数且只能增大不能回退。2.2 版本升级迁移流程旧版本 新版本版本一致旧版本 新版本是否是否应用启动检测数据库版本触发 onUpgrade正常打开数据库触发 onDowngrade / 报错oldVersion 2?执行版本1→2迁移oldVersion 3?执行版本2→3迁移版本已是最新降级不被支持提示用户重新安装2.3 完整的多版本迁移代码onUpgrade 回调中每个版本的迁移代码使用if (oldVersion N)的条件判断结构确保从任意旧版本升级到最新版本constSTORE_CONFIG:StoreConfig{name:moneytrack.db,securityLevel:SecurityLevel.S1,version:3,onUpgrade:(store,oldVersion,newVersion){console.log(数据库升级:${oldVersion}→${newVersion})// 版本 1 → 2新增 member_id 字段和 members 表if(oldVersion2){store.executeSql(ALTER TABLE transactions ADD COLUMN member_id TEXT DEFAULT \\)store.executeSql(ALTER TABLE transactions ADD COLUMN owner_id TEXT DEFAULT \\)store.executeSql(CREATE TABLE IF NOT EXISTS members ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, avatar TEXT, role INTEGER DEFAULT 0 ))console.log(迁移 v1→v2 完成新增 member 相关字段和表)}// 版本 2 → 3新增 attachments 附件表和 budget 预算表if(oldVersion3){store.executeSql(CREATE TABLE IF NOT EXISTS attachments ( id INTEGER PRIMARY KEY AUTOINCREMENT, transaction_id INTEGER NOT NULL, file_path TEXT NOT NULL, created_at TEXT DEFAULT (datetime(now)), FOREIGN KEY (transaction_id) REFERENCES transactions(id) ))store.executeSql(CREATE TABLE IF NOT EXISTS budgets ( id INTEGER PRIMARY KEY AUTOINCREMENT, month TEXT NOT NULL, amount REAL NOT NULL, category_id INTEGER, FOREIGN KEY (category_id) REFERENCES categories(id) ))console.log(迁移 v2→v3 完成新增附件表和预算表)}}}2.4 降级处理说明数据库版本号不能回退——如果将 StoreConfig 的 version 设为一个比当前数据库文件版本更小的值系统会触发onDowngrade回调或直接报错// ⚠️ 错误做法将已升级到版本 3 的数据库降回版本 2constSTORE_CONFIG:StoreConfig{version:2,// 当前数据库实际是版本 3会触发降级错误}降级场景的处理策略鸿蒙 RDB 默认不支持自动降级降级时会抛出异常如需降级正确做法是备份用户数据 → 删除旧数据库文件 → 重新创建新版本数据库 → 导入数据在开发测试阶段可通过卸载应用清除数据库文件来重置版本三、数据迁移策略详述3.1 各类表结构变更的操作变更类型SQL 操作是否影响存量数据新增字段ALTER TABLE ADD COLUMN否新增字段可设默认值新增表CREATE TABLE IF NOT EXISTS否修改字段类型创建新表 → 复制数据 → 删除旧表需要数据迁移删除字段创建新表不含该字段→ 复制数据 → 删除旧表会丢失该字段数据重命名表ALTER TABLE RENAME TO否但需更新引用3.2 迁移失败的处理迁移过程中的任何失败都可能导致数据库处于不一致状态。正确的做法是使用事务保证迁移的原子性// 使用事务包裹迁移逻辑onUpgrade:(store,oldVersion,newVersion){try{store.beginTransaction()if(oldVersion2){store.executeSql(ALTER TABLE ...)}if(oldVersion3){store.executeSql(CREATE TABLE ...)}store.commit()}catch(err){store.rollback()console.error(数据库迁移失败已回滚:,err)// 提示用户重新安装或联系技术支持// 鸿蒙 RDB 迁移失败后数据库文件可能无法正常使用}}迁移失败后的处理建议记录详细的错误日志包括 oldVersion、newVersion 和错误堆栈如果迁移失败建议提示用户应用数据需要重置请备份后重试在生产环境中重大迁移前应先备份数据库文件测试阶段应覆盖所有可能的版本升级路径3.3 字段兼容性扩展良好的前向兼容设计允许旧版本应用在新版数据库上正常运行至多丢失部分新功能。常见做法包括新字段设置默认值DEFAULT使用IF NOT EXISTS/IF EXISTS安全操作表结构查询时使用COALESCE处理可能不存在的字段// 兼容性查询COALESCE 处理新版本新增的字段constsqlSELECT *, COALESCE(member_id, ) as member_id FROM transactions四、项目代码案例4.1 从个人记账到家庭记账的数据模型扩展MoneyTrack 在演进过程中经历了从个人记账到家庭记账的数据模型扩展版本 1 → 版本 2个人 → 家庭transactions 表新增member_id字段TEXT默认空字符串transactions 表新增owner_id字段标识账单创建者新增 members 表家庭成员信息版本 2 → 版本 3功能增强新增 attachments 表账单附件新增 budgets 表月度预算4.2 迁移脚本的幂等性迁移脚本应具备幂等性——多次执行不会产生副作用使用IF NOT EXISTS创建表使用ALTER TABLE ... ADD COLUMN前检查列是否存在通过PRAGMA table_info版本条件判断确保每段迁移代码只执行一次4.3 测试迁移的最佳实践// 单元测试遍历所有版本升级路径asyncfunctiontestMigration(context:Context){consttestVersions[1,2,3]for(constfromVersionoftestVersions){for(consttoVersionoftestVersions){if(fromVersiontoVersion)continueconsole.log(测试迁移路径: v${fromVersion}→ v${toVersion})constconfig:StoreConfig{name:test_${fromVersion}_to_${toVersion}.db,version:toVersion,onUpgrade:/* 生产环境的迁移逻辑 */}// 验证迁移后表结构正确// 验证数据未丢失// 清理测试数据库}}}测试迁移的要点覆盖所有版本升级路径v1→v3、v2→v3 等使用真实数据的子集验证数据完整性验证迁移后所有 CRUD 操作正常测试迁移失败场景如磁盘空间不足五、参考文档RDB 数据库迁移指南SQLite ALTER TABLE 语法数据迁移最佳实践