PouchDB 7.2.0/7.2.1 新 indexeddb 适配器:基于 IndexedDB 原生索引的实现解析与迁移指南
PouchDB 7.2.0/7.2.1 新 indexeddb 适配器:基于 IndexedDB 原生索引的实现解析与迁移指南
导读
PouchDB 7.2.0/7.2.1 版本发布了一项备受关注的核心变更:全新的 indexeddb 适配器。它改变了 PouchDB 在浏览器端的数据组织方式——从过去依赖自定义内部表的 idb 适配器,转向直接使用 IndexedDB 的原生索引(native indexes)来加速查询。本文以官方发布文档 docs/posts/2020-02-12-pouchdb-7.2.0.md 为主线,结合仓库中 pouchdb-adapter-indexeddb 包的源码实现,讲清新适配器的注册方式、索引管理原理、与旧 idb 适配器的区别、Mango 查询的行为差异,以及升级迁移时需要留意的边界条件。读完本文,你将能判断自己的应用是否适合切换到 indexeddb,并能正确完成安装、切换与迁移。
一、发布背景:从 idb 到 indexeddb
PouchDB 长期以来在浏览器端的默认本地适配器是 idb,它把 IndexedDB 当作一个“自定义表”的存储介质:文档内容、索引数据等都以 PouchDB 自己定义的结构存放在 IndexedDB 的 object store 中,查询时需要 PouchDB 在 JavaScript 层自行完成索引扫描与过滤。
7.2.x 发布文档宣布了一个新的适配器(对应 issue #7618 的诉求):直接使用 IndexedDB 原生索引进行文档查询。即把 Mango 查询声明的字段直接映射为 IndexedDB 的 createIndex 索引,让浏览器数据库引擎负责索引维护与游标遍历,从而减少 JavaScript 层的扫描工作。
需要特别强调的是,发布文档明确说明这是一个新增的适配器,而不是对旧 idb 的原地升级:
- 旧的
idb适配器可以继续使用; - 新的适配器通过
indexeddb这个名称来注册; - 新旧两个适配器的数据不向后兼容,从旧库切换到新库需要自行完成数据迁移(发布文档原文即“data migration is left as an exercise for the reader”)。
二、新适配器的安装与启用
1. 独立包安装
新适配器以独立子包的形式发布,包名为 pouchdb-adapter-indexeddb(其 package.json 位于 packages/node_modules/pouchdb-adapter-indexeddb/package.json,声明为 PouchDB 的 monorepo 子包):
npm install pouchdb-adapter-indexeddb
2. 通过插件方式注册
该包通过标准的 PouchDB 插件机制接入,浏览器端的插件入口在 packages/node_modules/pouchdb/src/plugins/indexeddb.js:它先检查全局 PouchDB 对象是否存在,存在则调用 PouchDB.plugin(IndexeddbPouchPlugin) 完成注册。
PouchDB.plugin(require('pouchdb-adapter-indexeddb'));
var db = new PouchDB('mydb', { adapter: 'indexeddb' });
在适配器实现 packages/node_modules/pouchdb-adapter-indexeddb/src/index.js 中可以看到注册动作本身:
const ADAPTER_NAME = 'indexeddb';
IndexeddbPouch.valid = function () {
return true;
};
export default function (PouchDB) {
PouchDB.adapter(ADAPTER_NAME, IndexeddbPouch, true);
}
其中 PouchDB.adapter(name, adapter, true) 的第三个参数为 true,表示该适配器被标记为 PouchDB 自带的(browser default)适配器之一;api.type() 同样返回 'indexeddb',因此你可以通过 db.type() 来确认当前实例实际使用的适配器。
3. 与旧 idb 适配器的共存
启用新适配器后,同一域名下可以同时存在两种不同数据结构组织的数据库。命名与选择方式为:
| 适配器名 | 定位 | 数据结构 | 兼容性 |
|---|---|---|---|
idb |
原有默认适配器 | 自定义内部表结构 | 与旧版本数据兼容 |
indexeddb |
7.2.x 新增适配器 | IndexedDB 原生索引 | 与 idb 数据不兼容 |
在 setup.js 的 onupgradeneeded 中,新适配器会检查数据库的版本号来源:如果检测到该数据库是由旧 idb 适配器创建的(版本小于 versionMultiplier,即 10^13),会直接抛错:
throw new Error('Incorrect adapter: you should specify the "idb" adapter to open this DB');
从源码结构可以推断,PouchDB 团队选择“报错提示 + 手动迁移”而非静默转换,是为了避免在数据格式未经充分验证的情况下破坏用户数据。因此,如果你的现有应用还在使用 idb,切换前必须先设计并执行一次显式的数据搬迁(例如通过 replicate 到新库),再删除旧库。
三、源码级原理:原生索引如何被维护
1. 对象存储与版本管理
新适配器使用两个 object store(见 util.js):
const DOC_STORE = 'docs'; // 文档主存储,keyPath 为 'id'
const META_LOCAL_STORE = 'meta'; // 元数据与 _local 文档存储
IndexedDB 只允许在版本升级事务(onupgradeneeded)中修改 schema,因此 PouchDB 设计了一套“库版本 = 系统迁移号 × 10^13 + 当前时间戳”的编码方案(createIdbVersion),在 setup.js 中有详细注释:高位数(POUCHDB_IDB_VERSION,当前为 2)表示 PouchDB 层面的 schema 迁移版本,低位数(毫秒时间戳)表示用户侧因设计文档增删索引而触发的“用户迁移”,两者合并后仍安全地落在 Number.MAX_SAFE_INTEGER 范围内。
upgradePouchDbSchema 负责库级迁移:
- 版本 < 1:创建
docs存储(keyPathid)并建立唯一的seq索引,创建meta存储; - 版本 < 2:为
docs增加复合唯一索引deleted,id(用于按删除状态 + id 排序的全量查询),若库名包含-mrview-(旧的 map-reduce 视图库)则删除seq索引;同时把_local/文档从docs迁移到meta存储。
2. 原生索引的自动创建与回收:maintainNativeIndexes
新适配器最具特色的逻辑是 maintainNativeIndexes:每次打开数据库时,它扫描所有未删除且声明了 views 的设计文档,把 Mango 索引声明转换为 IndexedDB 原生索引,并同步清理多余的索引。
索引命名规则见 util.js 的 naturalIndexName:
function naturalIndexName(fields) {
return '_find_idx/' + fields.join('/');
}
例如 { fields: ['name', 'age'] } 会生成名为 _find_idx/name/age 的原生索引。索引 keyPath 的构造由 correctIndexFields 完成:
return ['deleted'].concat(
fields.map(function (field) {
if (['_id', '_rev', '_deleted', '_attachments'].includes(field)) {
return field.substr(1); // 顶层元数据字段去掉下划线
} else {
return 'data.' + sanitise(field, true); // 用户字段统一加 data. 前缀
}
})
);
也就是说,PouchDB 在 IndexedDB 中把每个文档的用户数据放在 data 属性下,而 _id、_rev、_deleted 等元数据平铺在顶层;每个原生索引都会把 deleted 放在 keyPath 最前面,便于查询时快速过滤已删除文档(data 内部还支持 foo.bar 这样的 JSON 路径点语法,由 sanitise 做字段名净化)。
打开库时的同步流程(setup.js 中):
- 枚举
docs中所有未删除的设计文档及其views,解析map.options.def.fields(rawIndexFields)得到期望索引集合; - 删除既不属于系统索引(
seq、deleted,id)也不在期望集合中的旧索引; - 为缺失的期望索引调用
createIndex创建。
由于 IndexedDB 的 schema 变更只能在版本升级时进行,而 PouchDB 用“时间戳版本”保证每次打开都能触发一次 upgrade 事务,因此索引的新增与回收可以安全地与多标签页场景并存——index.js 中实现了共享的 openDatabases 句柄池,并监听 onversionchange/onclose 把库标记为 versionChangedWhileOpen,下次访问时以当前版本重新打开,避免多标签页无限版本升级。
3. 原生索引上的查询路径
_find 查询的本地实现位于 find.js 的 query():它先读取对应设计文档,取出 rawIndexFields,然后用 indexHandle.openCursor(keyRange, opts.descending ? 'prev' : 'next') 在原生索引上做游标遍历,并在游标内处理 skip(cursor.advance(skip))与 limit,命中记录经 externaliseRecord 还原为对外可见的文档格式。相比旧 idb 需要把整表数据取回 JavaScript 层再排序过滤,原生索引方式把排序与范围过滤下沉到了浏览器引擎内部。
四、Mango 查询在 indexeddb 下的行为差异
新适配器的 README(packages/node_modules/pouchdb-adapter-indexeddb/README.md)明确列出了它与 CouchDB/PouchDB 默认行为之间已知的细微差异,使用前值得逐条核对:
1. 数据类型排序差异
在 {$lt: 10} 这类上界范围查询中,null、true、false 与极小的整数(Number.MIN_SAFE_INTEGER + 2 及以下)混排时的返回顺序可能与 CouchDB 的排序不一致。相关回归测试位于 tests/find/test-suite-1/test.data-type-order.js,如果你依赖严格的数据类型总序(例如把布尔值与数字混在同一索引字段上做范围查询),建议先在目标浏览器上跑一遍该测试再决定是否切换。
2. 对象(Object)无法被索引
CouchDB 支持把对象作为索引键,而 IndexedDB 原生索引不支持对象 keyPath。后果有两类:
- 用对象作为索引键查询时,结果不正确;
- 做
{$gt: 10}这类下界范围查询时,该字段上值为对象的文档不会出现在结果中。
README 说明这属于 IndexedDB 平台的固有限制,PouchDB 侧短期内难以修复。因此 Mango 索引字段应尽量避免使用对象类型。
3. partial_filter_selector 自动回退到 map-reduce
若 Mango 索引声明了 partial_filter_selector(局部过滤选择器),IndexedDB 原生索引无法对全部条目做条件子集索引,find.js 的 query() 会检测 isPartialFilterView 并回退到标准的 find-abstract-mapper(即 map-reduce 视图)路径(相关修复记录为 issue #8522 的讨论):
if (isPartialFilterView(ddoc, parts[1])) {
return fallback(signature, opts).then(resolve, reject);
}
viewCleanup 同样把这类视图的清理委托给 fallback 实现。这意味着使用了 partial_filter_selector 的索引会失去原生索引的性能收益,但换来的是与 CouchDB 一致的排序语义。
4. 如何判断当前使用的是哪个实现
README 建议通过 explain 查询来确认索引实际落到了哪种实现上。这是排查查询性能与排序行为最直接的入口。
五、迁移与切换注意事项
结合发布文档与源码,从 idb 切换到 indexeddb 时建议遵循以下步骤:
- 版本确认:确保 PouchDB 版本 >= 7.2.0(本仓库后续发布说明与变更记录见 docs/posts 下的各版本发布文档,例如 7.3.0、8.0.0 等)。
- 数据迁移:新旧库不兼容,且旧库用新适配器打开会直接报错。推荐使用 PouchDB 的 replicate 能力,把旧
idb库的数据同步到一个新命名的indexeddb库,验证数据完整后再废弃旧库;对带附件的库,注意meta中会记录idb_attachment_format('binary'或'base64',取决于浏览器 Blob 支持,见 setup.js 的checkBlobSupport逻辑),迁移后可用db.info()核对文档数与附件完整性。 - 行为验证:在新库上运行你的全部 Mango 查询(尤其是涉及
{$lt}/{$gt}范围、对象字段、partial_filter_selector的场景),用explain与 tests/find/test-suite-1/test.data-type-order.js 覆盖的类型顺序做对照。 - 多标签页:新适配器已处理多标签页版本冲突(
versionChangedWhileOpen机制),但仍建议在切换后进行多标签页并发写测试,观察是否有onblocked/onversionchange告警输出(见 setup.js 中的日志与错误处理)。
六、小结
PouchDB 7.2.0/7.2.1 的 indexeddb 适配器是浏览器端存储架构的一次重要演进:通过 _find_idx/<fields> 命名的原生索引、deleted 前置的复合 keyPath、以及打开库时自动维护索引的机制,把排序与范围过滤下沉到 IndexedDB 引擎;同时用 partial_filter_selector 回退、data. 前缀映射等设计保证了 Mango 查询语义的完整性。它并非旧 idb 的自动升级,而是一个需要显式选择、显式迁移的新选项。对查询性能敏感、且数据模型以标量字段为主的应用,值得基于本文的差异清单先在目标浏览器上验证后再切换到 indexeddb。