数据模型 Versioning 与迁移 — 应对应用升级的数据兼容性
一、引言
随着应用功能迭代，数据库表结构不可避免需要变更——新增字段、修改字段类型、拆分表结构等。如果直接修改表结构而不考虑数据兼容性，用户升级应用后将面临数据丢失或应用崩溃的风险。鸿蒙 RDB 提供了数据库版本管理和迁移机制，允许开发者在版本升级时执行有序的数据迁移。MoneyTrack 在从个人记账到家庭记账的演进过程中，通过合理的版本迁移策略实现了数据模型的无缝扩展。
二、核心知识点
2.1 数据库版本升级
RDB 数据库通过version属性管理数据库版本号。每次创建或打开数据库时，系统会比较当前版本号和期望版本号，如果不一致则触发迁移流程：
constSTORE_CONFIG:StoreConfig={name:'moneytrack.db',securityLevel:SecurityLevel.S1,version:3// 当前版本号}版本号从 1 开始递增，每次表结构变更时将版本号加 1。版本号是正整数且只能增大，不能回退。
2.2 版本升级迁移流程
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(oldVersion<2){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(oldVersion<3){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(oldVersion<2){store.executeSql('ALTER TABLE ...')}if(oldVersion<3){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 处理新版本新增的字段constsql=`SELECT *, 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(fromVersion>=toVersion)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 语法
- 数据迁移最佳实践