文章目录每日一句正能量导读一、为什么数据库升级比“加一列”复杂得多二、案例背景从 V1 演进到 V31. V1单表保存用户资料2. V2增加用户状态与索引3. V3拆分个人资料表三、坑一只判断目标版本跨版本用户直接失败四、坑二DDL 成功了数据回填却失败了为什么使用 INSERT OR IGNORE五、坑三默认值设计不当旧数据语义被改变六、坑四旧代码无法读取新结构降级后直接崩溃方案一优先做向前兼容而不是执行破坏性降级方案二增加兼容视图方案三拒绝危险降级七、建立迁移日志让线上问题可定位八、数据一致性校验不要只检查“SQL 没报错”1. 行数校验2. 缺失记录校验3. 重复与孤儿记录校验4. 内容摘要校验九、灰度升级数据库变更必须配发布开关建议关注的指标止损开关怎么设计十、性能优化避免升级时卡住首屏小数据量一次事务完成中等数据量分批迁移并记录游标大数据量前台完成最小升级后台渐进回填十一、测试矩阵至少覆盖这些场景十二、可复用的迁移管理器十三、校企合作课堂中的教学建议十四、结语每日一句正能量河流遇到礁石会改变流向却也因此激荡出更美丽的浪花。阻碍可以成为风景。礁石没有消灭河流只是让它改变了形态——产生了声音、形状和生命力。一帆风顺的河流是平静的甚至乏味的。生命的美感往往来自与阻力的碰撞。导读本文以一个从旧版本升级到 HarmonyOS 6.1 的本地关系型数据库改造为背景完整记录 Schema 变更、迁移脚本、降级兼容、数据一致性校验与灰度发布方案。示例使用 ArkTS 风格伪代码与 SQL具体接口签名请以项目所使用的 HarmonyOS SDK 与 ArkData 官方文档为准。一、为什么数据库升级比“加一列”复杂得多在课堂项目或早期原型中我们通常直接修改建表语句然后重新安装应用验证功能。可一旦应用已经发布用户设备中保存的是不同历史版本的真实数据库有人从 V1 升级有人从 V2 升级也有人首次安装 V3。此时数据库升级不再是一次简单的 DDL 修改而是一条必须覆盖多种入口状态的迁移链。我在一次 HarmonyOS 6.1 适配中遇到的典型问题是新版本需要给用户表增加状态字段同时把较大的个人资料字段拆分到独立表。开发环境清库后运行正常但灰度用户出现启动失败、旧数据丢失、部分记录重复等问题。复盘后发现问题集中在四个方面只维护“最新建表 SQL”没有维护 V1→V2、V2→V3 的增量脚本。Schema 变更与数据回填没有放在同一个事务中。新代码立即依赖新字段导致迁移未完成时就开始查询。发布策略只有“全量或撤回安装包”没有数据库层面的止损开关。数据库升级的核心目标不是“脚本跑完”而是做到四件事数据不丢、过程可重入、失败可回滚、版本可观测。二、案例背景从 V1 演进到 V3本文示例数据库名为app_data.db。1. V1单表保存用户资料CREATETABLEIFNOTEXISTSuser(idINTEGERPRIMARYKEYAUTOINCREMENT,nameTEXTNOTNULL,profile_jsonTEXT,created_atINTEGERNOTNULL);2. V2增加用户状态与索引业务新增“正常、停用、待完善”三种状态需要增加status字段并为列表筛选增加索引。ALTERTABLEuserADDCOLUMNstatusINTEGERNOTNULLDEFAULT0;CREATEINDEXIFNOTEXISTSidx_user_statusONuser(status);3. V3拆分个人资料表由于profile_json体积不断增大用户列表查询不应再扫描大字段因此把资料拆到user_profile表。CREATETABLEIFNOTEXISTSuser_profile(user_idINTEGERPRIMARYKEY,profile_jsonTEXTNOTNULLDEFAULT{},migrated_atINTEGERNOTNULL,FOREIGNKEY(user_id)REFERENCESuser(id));数据库版本图如下下载数据库版本图这里有一个重要原则首次安装应直接创建 V3 的最终结构历史用户升级则按 V1→V2→V3 顺序执行。不要让首次安装也重复执行全部迁移脚本否则会增加复杂度和测试成本。三、坑一只判断目标版本跨版本用户直接失败很多代码只写成下面这样if(oldVersion3){awaitmigrateToV3(store);}看似覆盖了旧版本实际隐藏了一个问题migrateToV3()如果默认status字段已经存在那么 V1 用户直接调用时就会失败。可靠做法是把升级拆成连续步骤并明确每一步的前置版本。asyncfunctionupgradeDatabase(store:relationalStore.RdbStore,oldVersion:number,newVersion:number):Promisevoid{letcurrentoldVersion;if(current2newVersion2){awaitmigrateV1ToV2(store);current2;}if(current3newVersion3){awaitmigrateV2ToV3(store);current3;}if(current!newVersion){thrownewError(数据库升级路径不完整${oldVersion}-${newVersion});}}这种写法有三个优点每个脚本职责单一便于单元测试。可验证所有历史路径而不是只测“上一个版本”。将来新增 V4 时只需增加 V3→V4不必修改旧脚本。四、坑二DDL 成功了数据回填却失败了V2→V3 的迁移包含“建表”和“复制数据”。如果建表成功后应用被杀死而复制尚未完成下次启动可能发现新表已存在于是误判迁移成功。解决方法是把 Schema 变更、数据回填、校验和迁移日志写入同一事务。asyncfunctionmigrateV2ToV3(store:relationalStore.RdbStore):Promisevoid{awaitstore.beginTransaction();try{awaitstore.executeSql(CREATE TABLE IF NOT EXISTS user_profile ( user_id INTEGER PRIMARY KEY, profile_json TEXT NOT NULL DEFAULT {}, migrated_at INTEGER NOT NULL ));constnowDate.now();awaitstore.executeSql(INSERT OR IGNORE INTO user_profile(user_id, profile_json, migrated_at) SELECT id, COALESCE(profile_json, {}),${now}FROM user);awaitverifyV3Migration(store);awaitstore.executeSql(INSERT OR REPLACE INTO migration_log( version, status, finished_at ) VALUES (3, SUCCESS,${now}));awaitstore.commit();}catch(error){awaitstore.rollBack();thrownewError(V2→V3 迁移失败${String(error)});}}迁移流程如下下载迁移脚本执行流程图为什么使用INSERT OR IGNORE迁移脚本应尽量具备幂等性。若应用在提交前异常退出事务会回滚若某些厂商环境或业务补偿流程导致脚本再次执行INSERT OR IGNORE可以避免主键重复。幂等不代表忽略所有错误而是让“重复执行同一安全步骤”不会破坏数据。五、坑三默认值设计不当旧数据语义被改变新增非空字段时最常见做法是ALTERTABLEuserADDCOLUMNstatusINTEGERNOTNULLDEFAULT0;但必须确认0的业务含义。假设新系统中0表示“待完善”那么所有历史用户都会被错误标记。更稳妥的方式是分两步ALTERTABLEuserADDCOLUMNstatusINTEGER;UPDATEuserSETstatus1WHEREstatusISNULL;待所有历史数据回填完成后再由业务层保证新写入不为空。SQLite 类数据库对“修改字段约束”的支持通常有限直接把可空字段改成非空字段可能需要重建表因此线上升级更适合采用“先扩展、后收缩”的策略先增加可空字段。新旧代码同时兼容字段为空。后台或迁移脚本完成回填。观察一个发布周期。再考虑收紧约束或重建表。六、坑四旧代码无法读取新结构降级后直接崩溃移动端应用被覆盖安装后数据库通常不会自动恢复到旧版本。即使应用商店撤回新包已经升级数据库的用户也可能重新安装旧包。旧代码若只认识 V2而数据库已经是 V3就会出现“代码降级、数据不降级”的不对称状态。方案一优先做向前兼容而不是执行破坏性降级V3 建立user_profile表后暂时保留user.profile_json字段不立即删除。新代码写入时同时更新新表和旧字段asyncfunctionsaveProfile(store:relationalStore.RdbStore,userId:number,profileJson:string):Promisevoid{awaitstore.beginTransaction();try{awaitstore.executeSql(INSERT OR REPLACE INTO user_profile(user_id, profile_json, migrated_at) VALUES (?, ?, ?),[userId,profileJson,Date.now()]);// 兼容旧版本应用读取。awaitstore.executeSql(UPDATE user SET profile_json ? WHERE id ?,[profileJson,userId]);awaitstore.commit();}catch(error){awaitstore.rollBack();throwerror;}}双写会增加成本但在灰度阶段很有价值。等新版本覆盖率足够高、回滚窗口关闭后再通过后续版本停止双写。方案二增加兼容视图如果旧查询只依赖固定字段可以建立视图向旧逻辑提供稳定结构CREATEVIEWIFNOTEXISTSuser_compatASSELECTu.id,u.name,COALESCE(p.profile_json,u.profile_json,{})ASprofile_json,u.created_at,u.statusFROMuseruLEFTJOINuser_profile pONp.user_idu.id;方案三拒绝危险降级当检测到数据库版本高于代码支持版本时不要擅自删表或清库。应进入受控状态例如提示用户升级应用、仅开放只读功能并上报版本信息。functionassertDatabaseCompatible(dbVersion:number):void{constmaxSupportedVersion3;if(dbVersionmaxSupportedVersion){thrownewError(当前应用最高支持数据库 V${maxSupportedVersion}实际为 V${dbVersion});}}七、建立迁移日志让线上问题可定位建议在 V1 就预置迁移日志表或在首次需要迁移时补建。CREATETABLEIFNOTEXISTSmigration_log(versionINTEGERPRIMARYKEY,statusTEXTNOTNULL,started_atINTEGER,finished_atINTEGER,error_codeTEXT,app_versionTEXT);每次迁移至少记录起始数据库版本与目标版本。应用版本、系统版本、设备类型。迁移开始时间与结束时间。执行结果、错误码、失败步骤。迁移前后记录数摘要。日志中不要写入姓名、手机号、Token、完整业务内容等敏感信息。需要排查具体记录时应使用匿名化 ID 或哈希摘要。八、数据一致性校验不要只检查“SQL 没报错”迁移成功必须有可计算的验收标准。V2→V3 至少应检查以下内容。1. 行数校验SELECTCOUNT(*)ASuser_countFROMuser;SELECTCOUNT(*)ASprofile_countFROMuser_profile;若每个用户都必须有资料记录则两个数量应一致如果允许空资料则应明确差异范围。2. 缺失记录校验SELECTCOUNT(*)ASmissing_countFROMuseruLEFTJOINuser_profile pONp.user_idu.idWHEREp.user_idISNULL;3. 重复与孤儿记录校验SELECTuser_id,COUNT(*)AScFROMuser_profileGROUPBYuser_idHAVINGc1;SELECTCOUNT(*)ASorphan_countFROMuser_profile pLEFTJOINuseruONu.idp.user_idWHEREu.idISNULL;4. 内容摘要校验对大字段逐条比较成本较高可以计算业务摘要。例如统计空对象数量、资料平均长度或抽样比较哈希。不要只比较文件大小因为数据库页复用、索引和日志都可能影响文件体积。interfaceMigrationCheckResult{userCount:number;profileCount:number;missingCount:number;orphanCount:number;invalidStatusCount:number;}functionisMigrationValid(r:MigrationCheckResult):boolean{returnr.userCountr.profileCountr.missingCount0r.orphanCount0r.invalidStatusCount0;}九、灰度升级数据库变更必须配发布开关数据库脚本在测试机上通过不等于能覆盖真实世界的旧数据。建议采用四阶段灰度离线样本测试保存 V1、V2 的脱敏数据库样本自动执行所有升级路径。内部与小流量测试先覆盖内部账号和约 1% 用户。扩大灰度观察 24 小时后逐步扩大到 10%、30%。全量发布保持远程开关和只读降级能力持续观察至少一个版本周期。下载灰度升级与数据一致性校验图建议关注的指标数据库打开失败率。单次迁移成功率与 P50/P95 耗时。升级后首次冷启动耗时。数据缺失率、重复率、孤儿记录数。与数据库相关的崩溃率和异常码分布。迁移完成后业务关键指标是否突变。止损开关怎么设计数据库迁移本身通常在本地执行无法完全依赖服务端但可以通过远程配置控制高风险功能interfaceDatabaseFeatureFlags{enableProfileTableRead:boolean;enableProfileDualWrite:boolean;enableBackgroundBackfill:boolean;}推荐发布顺序先发布“建表 双写”读取仍走旧字段。确认迁移成功率后灰度开启新表读取。出现异常时关闭新表读取继续保留双写。稳定后停止旧字段写入最后才考虑删除旧字段。这就是典型的“扩展—迁移—切流—收缩”模型比一次性修改可靠得多。十、性能优化避免升级时卡住首屏数据库升级往往发生在应用首次打开阶段。如果一次迁移数十万条记录用户会感知明显卡顿甚至触发系统无响应。可以按数据规模选择策略小数据量一次事务完成记录少、字段简单时一次事务最容易保证原子性。中等数据量分批迁移并记录游标CREATETABLEIFNOTEXISTSmigration_checkpoint(task_nameTEXTPRIMARYKEY,last_idINTEGERNOTNULL,statusTEXTNOTNULL);每次处理 5002000 条提交后更新last_id。下次启动从检查点继续。批大小应通过真机测试确定不应照搬固定数值。大数据量前台完成最小升级后台渐进回填前台只创建新表、索引和兼容结构确保应用可用大字段复制放到后台任务中。读取时采用“新表优先、旧字段兜底”直到回填完成。asyncfunctionloadProfile(store:relationalStore.RdbStore,userId:number):Promisestring{constnewValueawaitqueryProfileTable(store,userId);if(newValue!undefined){returnnewValue;}returnawaitqueryLegacyProfile(store,userId)??{};}十一、测试矩阵至少覆盖这些场景建议在 CI 或回归测试中维护以下矩阵场景初始状态预期结果首次安装无数据库直接创建 V3常规升级V2 完整数据库成功迁移到 V3跨版本升级V1 完整数据库顺序执行 V1→V2→V3空数据库V1 结构、无数据正常迁移大数据量V2十万级记录耗时可控、无 ANR异常中断回填中强制退出下次可恢复或事务回滚磁盘空间不足可用空间极低明确报错、不破坏旧数据脏数据非法状态、空字段校验失败并记录原因应用降级V3 数据库 V2 代码进入兼容或受控拒绝状态重复执行已完成 V3 后再触发结果不变、无重复数据测试时不要只构造“完美旧库”。线上最难处理的往往是历史 Bug 留下的脏数据例如空字符串、重复业务键、半完成记录和异常时间戳。十二、可复用的迁移管理器下面给出一个适合项目化封装的骨架typeMigration{from:number;to:number;run:(store:relationalStore.RdbStore)Promisevoid;};classDatabaseMigrationManager{privatereadonlymigrations:Migration[][{from:1,to:2,run:migrateV1ToV2},{from:2,to:3,run:migrateV2ToV3}];asyncmigrate(store:relationalStore.RdbStore,oldVersion:number,targetVersion:number):Promisevoid{if(oldVersiontargetVersion){thrownewError(检测到数据库降级禁止自动执行破坏性操作);}letcurrentoldVersion;while(currenttargetVersion){conststepthis.migrations.find(itemitem.fromcurrent);if(!step){thrownewError(缺少从 V${current}开始的迁移脚本);}awaitstep.run(store);currentstep.to;}if(current!targetVersion){thrownewError(迁移终点异常V${current});}}}实际项目还应补充锁机制避免多个 Ability 或并发任务同时启动迁移同时对错误进行分类例如 SQL 语法错误、磁盘不足、数据校验失败和版本路径缺失。只有明确分类线上告警才有行动价值。十三、校企合作课堂中的教学建议数据库迁移非常适合作为综合实训题因为它同时考查 ArkTS、SQL、事务、异常处理、测试设计和发布工程。课堂中可以给学生一份 V1 数据库和业务需求让小组完成 V3 迁移并设置以下验收项不允许清库重建。必须支持 V1、V2 两种升级入口。必须提供失败回滚与迁移日志。必须编写数据一致性校验。必须提交灰度方案和回滚说明。必须在真机上记录迁移耗时。这种训练比单纯实现增删改查更接近企业研发也能帮助毕业生在面试中讲清楚“如何保证线上数据安全”。十四、结语HarmonyOS 6.1 适配中的数据库升级真正困难的不是某条 SQL而是如何管理版本状态和失败边界。一个可靠方案应坚持以下原则Schema 变更按连续版本拆分不跨级猜测。DDL、数据回填、校验和日志尽量处于同一事务。迁移脚本具备幂等性和明确的前置条件。优先采用向前兼容谨慎处理应用降级。用数据指标验证迁移而不是只看“没有报错”。通过灰度、双写、读取开关和兼容视图降低发布风险。旧字段的删除属于最后一步而不是第一步。数据库承载的是用户长期积累的数据。对开发者而言升级脚本只运行几秒对用户而言那可能是几年记录能否被安全保留。把迁移做成工程能力而不是一次性补丁才是 HarmonyOS 应用从“能运行”走向“可长期维护”的关键。转载自https://blog.csdn.net/u014727709/article/details/162993987欢迎 点赞✍评论⭐收藏欢迎指正
