鸿蒙 RDB 数据库五个硬约束:securityLevel 缺失即崩、版本号只能升、事务不能嵌套与 batchInsert 的
鸿蒙的 relationalStore 底层就是 SQLite,但在它外面套了一层 store 生命周期管理、权限模型和 ArkTS 的异步封装。这层封装带来五个不写在文档首页、但一定会踩的硬约束。下面按「建库 → 迁移 → 事务 → 批量 → 并发」的顺序一次讲透。
一、getRdbStore 的 storeConfig:三项必须显式
很多人照着示例只写 name 就跑了,本地能跑,上真机换设备就崩。原因是 storeConfig 里有两项直接决定数据落在哪个安全域、是否加密,缺省值在不同 API 版本上并不一致:
import { relationalStore } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';
const STORE_CONFIG: relationalStore.StoreConfig = {
name: 'workshop.db', // 必填:库文件名,不带路径
securityLevel: relationalStore.SecurityLevel.S1, // 必填:S1~S4
encrypt: false, // 建议显式:true 时密钥由系统托管
customDir: 'report' // 可选:库落到 /data/storage/el2/database/report/
};
export async function openStore(ctx: common.UIAbilityContext): Promise {
// 1) 先看有没有可用实例,避免同库多实例并发写
const store = await relationalStore.getRdbStore(ctx, STORE_CONFIG);
// 2) 建表用 executeSql,注意 executeSql 返回 Promise<void>
await store.executeSql(
'CREATE TABLE IF NOT EXISTS work_order (' +
' id INTEGER PRIMARY KEY AUTOINCREMENT,' +
' code TEXT NOT NULL UNIQUE,' +
' line TEXT,' +
' qty INTEGER DEFAULT 0,' +
' created_at INTEGER)'
);
return store;
}
三个坑逐条说清:
1)securityLevel 缺失不等于「默认安全」。 它是必填项,类型检查阶段能过、运行时在部分镜像上直接抛 14800000(内部错误)。S1 表示「低敏感」,S4 表示「极高敏感」,同一个库一旦用某个级别建过,改级别不会迁移数据,只会打开失败。工程里最好把它做成常量,全项目引用一处。
2)encrypt: true 的库不能被外部工具直接打开。 做数据导出、崩溃现场分析时,加密库必须走应用内的 store.backup() / restore(),用 hdc file recv 拖出来的 .db 文件在 SQLite 客户端里只会报「file is not a database」。这不是文件损坏。
3)同库多实例是并发写的头号来源。 getRdbStore 对同一个 name 多次调用,返回的对象可能不是同一个;每个实例有自己的连接和事务状态。工程里应当用单例持有 store,而不是在几十个页面里各写一遍 getRdbStore。
二、version 只能单调递增,onUpgrade 只收到「旧版本号」
版本迁移的注册方式:
const CFG: relationalStore.StoreConfig = {
name: 'workshop.db',
securityLevel: relationalStore.SecurityLevel.S1,
encrypt: false
};
const store = await relationalStore.getRdbStore(ctx, CFG);
// 只有 store.version 与当前库不一致时才会触发
store.version = 3;
store.on('versionChange' as any, () => {});
// 旧 API 用 StoreConfig 回调,新写法直接比较后手工迁移:
const cur = store.version; // 首次建库为 0
if (cur < 1) { await store.executeSql('ALTER TABLE work_order ADD COLUMN shift TEXT'); }
if (cur < 2) { await store.executeSql('ALTER TABLE work_order ADD COLUMN batch_no TEXT'); }
if (cur < 3) { await store.executeSql('CREATE INDEX IF NOT EXISTS idx_code ON work_order(code)'); }
if (cur !== 3) { store.version = 3; }
硬约束有两条:
version 不能回退。 把 version 从 3 写回 2,库里会记成 2,但表结构还是 3 的——后续 2→3 的判断就会把已存在的列再加一次,报 duplicate column name。发版前如果回滚了代码,一定要同时清掉数据目录或用 IF NOT EXISTS 兜。
onUpgrade 拿不到「从几到几」。 回调只给新版本号,旧版本要在回调里自己从 store.version 读。所以正确的迁移写法是「按版本号逐级 if」,而不是「在回调里清库重建」——后者在灰度回滚时会把用户数据全清掉。
三、事务:不支持嵌套,ResultSet 不 close 会卡死后续写
// 正确:一个事务包住一组写
async function importOrders(store: relationalStore.RdbStore, rows: Order[]): Promise<void> {
store.beginTransaction();
try {
for (const r of rows) {
await store.insert('work_order', {
code: r.code, line: r.line, qty: r.qty, created_at: Date.now()
}, relationalStore.ConflictResolution.ON_CONFLICT_IGNORE);
}
store.commit();
} catch (e) {
store.rollback();
throw e as Error;
}
}
事务是连接级的、不能嵌套。 在 beginTransaction() 之后又调一次,行为是「第二个 begin 被忽略」,随后第一个 commit() 会把两批数据一起提交,第二个 rollback() 则直接抛「no transaction」。表现就是「回滚没生效、脏数据进库」。要支持嵌套语义,只能自己用计数器和 SAVEPOINT 手写。
ResultSet 必须 close()。 查询返回的 relationalStore.ResultSet 底层挂着游标,不关就一直占着连接。在同一 store 上做「边查边写」最容易踩:查询结果没关,紧接着的 insert 会一直 pending,日志里只有一行不起眼的 database is locked。规矩是 try/finally 里一定 close:
async function pickPending(store: relationalStore.RdbStore): Promise<string[]> {
const rs = await store.querySql('SELECT code FROM work_order WHERE qty = 0 LIMIT 100');
const out: string[] = [];
try {
while (rs.goToNextRow()) { out.push(rs.getString(rs.getColumnIndex('code'))); }
} finally {
rs.close(); // 少这一行,后面的写全会卡
}
return out;
}
四、batchInsert 单次 199 条,超了静默截断
store.batchInsert(table, values) 是绕开逐条 SQL 解析的最快路径,但它有一个来自 SQLite 变量上限的硬顶:单次调用最多 199 条(不是 200,也不是 999)。超过的部分不会报错,返回值直接小于入参数组长度——很多「同步少了几十条」的问题就出在这里。
const CHUNK = 199;
async function bulkInsert(store: relationalStore.RdbStore, rows: relationalStore.ValuesBucket[]): Promise<number> {
let ok = 0;
store.beginTransaction(); // 事务把多次 batch 包起来,速度再翻倍
try {
for (let i = 0; i < rows.length; i += CHUNK) {
const part = rows.slice(i, i + CHUNK);
const n = await store.batchInsert('work_order', part);
if (n !== part.length) { // 一定要比对,别只判断 > 0
console.warn('batchInsert 少写 ' + (part.length - n) + ' 条');
}
ok += n;
}
store.commit();
} catch (e) {
store.rollback();
throw e as Error;
}
return ok;
}
另外,ValuesBucket 的值类型只允许 number | string | boolean | Uint8Array | null。undefined 会让你在真机上静默丢字段,Date 对象会被忽略,所以时间统一存 number(毫秒时间戳),要展示时再格式化。
五、三类并发写入卡死的现场与判据
1)页面各持一个 store,同时写同库。 判据:崩溃日志里出现 database is locked,且复现路径一定是「两个页面几乎同时提交」。修法:单例 + 写操作串行化(用一个 Promise 链做队列)。
2)事务里做 await 网络请求。 事务一开,库的写锁就在手里,等网络几百毫秒到几秒,其它写全阻塞。判据:慢的时候整体卡顿,快的时候一切正常。修法:先请求、再开事务写。
3)onUpgrade 里做重活。 迁移里跑「读全表 → 逐条改写」几十万行,首次启动会直接 ANR。判据:只有升级后的第一次启动慢。修法:迁移只做 DDL,数据搬迁放到启动后的后台任务里。
// 写队列:把并发写压成串行
let chain: Promise<unknown> = Promise.resolve();
export function enqueueWrite<T>(fn: () => Promise<T>): Promise<T> {
const next = chain.then(fn, fn);
chain = next.catch(() => undefined);
return next;
}
六、上线自检清单
[ ] storeConfig 里 securityLevel 显式写了,全项目只在一处定义
[ ] store 是单例,业务层不直接调 getRdbStore
[ ] version 只单调递增,迁移逻辑是「逐级 if (cur < N)」而不是清库重建
[ ] 每个 ResultSet 都在 finally 里 close
[ ] 事务内没有任何网络/文件 IO,事务不嵌套
[ ] batchInsert 分片 199,且每次都比对返回值与入参长度
[ ] ValuesBucket 里没有 undefined / Date,时间统一存毫秒数
[ ] 首次升级路径在真机上测过一次(旧版本装→升到新版本)
RDB 的问题普遍不是 SQL 写错,而是「连接、锁、版本」这三件基础设施的事没理清。把上面五条硬约束固化成团队约定,剩下的增删改查就只是查文档的活。
- 点赞
- 收藏
- 关注作者
评论(0)