跳转至

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 时执行:

this.util.db = MetaHelper.get(dbSchema)   // 用【上次 upgrade 时缓存的 schema】

把你传进去的表定义整个丢弃。 所以:

  • dataType / default / notNull 的校验,升级安装按旧 schema 走、全新安装按新 schema 走
  • ⇒ 这就是 SPEC-013 说的「两套 schema」

结论:加列的正确姿势

若真要加列,选同版本 + 纯 JS 侧字段这条路,并遵守:

  1. 不写 dataType / default / notNull —— 它们只在全新安装生效,写了就是行为分叉
  2. 显式写 enableSearch: false —— 缺省是 true(worker TableMeta.setColumn :211), 不写就是「全新安装有索引、升级安装没有」
  3. 🔴 这一列永远不进 where —— 它没有索引,进 where 要么抛 no_index_found, 要么退化成全表扫(而 jsstore 在 MV3 SW 里跑在主线程)
  4. 列不是表:从 columns 里删掉列不触发 deleteObjectStore (worker :642 那条只对 tables 数组成立)—— 铁律 20 管的是表,不是列

一个必须提前知道的出口

新列会静默随云同步上行 —— 同步 payload 是无白名单的整行 for...in 拷贝 (parse-data.ts:174 的 exNullData)。加任何列之前先确认这条出口可接受。

另一个静默杀手

带 id 的 insert(upsert:true) 是 put,整对象替换 —— 新字段整个消失且不报错。 今天安全,因为 addSearchData 的 item 不带 id(自增补); 但任何未来的「云端拉回整行覆盖本地」路径都会踩中。