jsstore 给已有表加列的真实机理¶
🔴 本文订正一个流传过的失实结论:「本项目从未给已有表加过列」——错的。 v0.9.9 给
MapTaskData加过taskId列并 bump DB 1→2 (docs/changelog/development-log-archive-v0.10.0-84.md:8442-8450),而且栽了: 至今src/utils/jsstore/search-data.ts:137-172两处注释写着 「不再走 jsstore 的where:{taskId}」「老 DB 升级后这条 where 容易给 0 行」, 被迫改成全表 select + JS 端 filter(getListByTaskId扫 200k 行)。 那不是玄学,机理如下。
onupgradeneeded 里只有两条路会建索引¶
读 node_modules/jsstore/dist/jsstore.worker.js:601-637:
| # | 条件 | 动作 |
|---|---|---|
| ① | store 不存在 | createObjectStore + columns.forEach(addColumn)(:602-606) |
| ② | table.alter[version].add 有声明 |
按声明 addColumn(:613-618) |
🔴 给已有表加列、不写 alter ⇒ addColumn 永远不被调用。
三种做法的实测结果¶
对抗工作流用 fake-indexeddb + 真 jsstore 4.9.0(模拟 MV3 SW 的 IS_WORKER=false)实测:
| 做法 | 结果 |
|---|---|
bump version + 新列 enableSearch:true、无 alter |
原生 indexNames 不含新列;where:{新列} 直接抛 no_index_found: Query can not be executed without index ← 这就是 taskId 事故的真相 |
bump version + alter{N:{add:{...}}} |
indexNames 含新列,where 正常 |
| 同版本加列(不 bump) | initDb 返回 isCreated=false;update / insert 写新字段都持久化、读得回 |
为什么同版本加列能写进去¶
QueryManager.initDb(worker :4870-4897)在 isCreated=false 时执行:
把你传进去的表定义整个丢弃。 所以:
dataType/default/notNull的校验,升级安装按旧 schema 走、全新安装按新 schema 走- ⇒ 这就是 SPEC-013 说的「两套 schema」
结论:加列的正确姿势¶
若真要加列,选同版本 + 纯 JS 侧字段这条路,并遵守:
- 不写
dataType/default/notNull—— 它们只在全新安装生效,写了就是行为分叉 - 显式写
enableSearch: false—— 缺省是true(workerTableMeta.setColumn :211), 不写就是「全新安装有索引、升级安装没有」 - 🔴 这一列永远不进
where—— 它没有索引,进where要么抛no_index_found, 要么退化成全表扫(而 jsstore 在 MV3 SW 里跑在主线程) - 列不是表:从
columns里删掉列不触发deleteObjectStore(worker:642那条只对tables数组成立)—— 铁律 20 管的是表,不是列
一个必须提前知道的出口¶
新列会静默随云同步上行 —— 同步 payload 是无白名单的整行 for...in 拷贝
(parse-data.ts:174 的 exNullData)。加任何列之前先确认这条出口可接受。
另一个静默杀手¶
带 id 的 insert(upsert:true) 是 put,整对象替换 —— 新字段整个消失且不报错。
今天安全,因为 addSearchData 的 item 不带 id(自增补);
但任何未来的「云端拉回整行覆盖本地」路径都会踩中。