PouchDB 7.2.0/7.2.1 新 indexeddb 适配器:基于 IndexedDB 原生索引的实现解析与迁移指南

原创2026-09-20 12:45:311,636 阅读
文章标签:数据库文档数据库数据同步KV存储前端

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 存储(keyPath id)并建立唯一的 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 中):

  1. 枚举 docs 中所有未删除的设计文档及其 views,解析 map.options.def.fields(rawIndexFields)得到期望索引集合;
  2. 删除既不属于系统索引(seq、deleted,id)也不在期望集合中的旧索引;
  3. 为缺失的期望索引调用 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 时建议遵循以下步骤:

  1. 版本确认:确保 PouchDB 版本 >= 7.2.0(本仓库后续发布说明与变更记录见 docs/posts 下的各版本发布文档,例如 7.3.0、8.0.0 等)。
  2. 数据迁移:新旧库不兼容,且旧库用新适配器打开会直接报错。推荐使用 PouchDB 的 replicate 能力,把旧 idb 库的数据同步到一个新命名的 indexeddb 库,验证数据完整后再废弃旧库;对带附件的库,注意 meta 中会记录 idb_attachment_format('binary' 或 'base64',取决于浏览器 Blob 支持,见 setup.js 的 checkBlobSupport 逻辑),迁移后可用 db.info() 核对文档数与附件完整性。
  3. 行为验证:在新库上运行你的全部 Mango 查询(尤其是涉及 {$lt}/{$gt} 范围、对象字段、partial_filter_selector 的场景),用 explain 与 tests/find/test-suite-1/test.data-type-order.js 覆盖的类型顺序做对照。
  4. 多标签页:新适配器已处理多标签页版本冲突(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。

登录后查看全文
pouchdb