PouchDB 6.4.2 深度解析:Safari 存储引擎从 WebSQL 切换到 IndexedDB 的迁移实战指南

原创2026-09-20 13:15:401,623 阅读
文章标签:数据库文档数据库数据同步KV存储前端

PouchDB 6.4.2 深度解析:Safari 存储引擎从 WebSQL 切换到 IndexedDB 的迁移实战指南

PouchDB 6.4.2 是一个承前启后的版本:它正式让 IndexedDB 成为 PouchDB 在 Safari 中的默认存储引擎,并宣告 WebSQL 进入"只维护、不演进"的退役通道。本文以该版本发布说明为核心,梳理 WebSQL 从"救火队员"到"历史包袱"的完整历程,结合当前仓库源码解释适配器自动选择与防数据丢失的降级保护逻辑,并给出面向存量用户的 WebSQL → IndexedDB 复制迁移完整方案,最后展望 7.0 中 Promise Polyfill 移除与 fetch API 切换等破坏性变更,帮助开发者平稳度过这次存储引擎换代。

版本背景:一个版本、一次存储引擎的默认切换

在 6.4.2 之前,PouchDB 在 Safari 中默认使用 WebSQL;而自本版本起,PouchDB 在 Safari 中默认使用 IndexedDB,WebSQL 则计划在未来的版本中逐步移除支持。对于只使用最新浏览器环境的开发者来说,这次切换几乎是透明的——数据库 API、复制(replication)、MapReduce 与 find 插件的行为都不变,变的只是底层存储实现。

值得注意的是,Safari 用户并不会因此丢失旧数据。6.4.2 仍然同时支持 WebSQL 与 IndexedDB 两种适配器,这也为下面的迁移方案留出了操作空间。

WebSQL 的前世今生:从"救火队员"到"历史包袱"

发布说明用一个时间线讲述了 WebSQL 与 PouchDB 的故事:

  1. 约 5 年前(2012 年前后):PouchDB 首次支持 WebSQL,最初是为了支持 Opera WebSQL,因为当时 Safari 缺少 IndexedDB 支持,WebSQL 补上了这块短板,让 PouchDB 得以覆盖更广泛的浏览器。
  2. Opera 转向 Blink/Chromium:Opera 随之获得 IndexedDB 支持,WebSQL 对它而言不再必要。
  3. WebSQL 未能成为 Web 标准:W3C 停止了对 WebSQL 规范的推进,Safari 从 7.1 开始支持 IndexedDB。
  4. Safari 的 IndexedDB 早期实现 bug 太多:PouchDB 无法直接采用,直到 WebKit 团队经过多个版本的修复,IndexedDB 在 Safari 中才足够稳定。
  5. 6.4.2 落地:IndexedDB 成为 PouchDB 在 Safari 中的默认存储引擎。

这个时间线揭示了 PouchDB 的一个核心工程理念:存储适配器不是"多多益善",而是每个新增后端都意味着持续的维护成本。发布说明明确指出,此前所有与存储相关的功能改进都需要在 WebSQL 上重复实现整套代码与工作,切换到 IndexedDB 后这部分重复劳动被大幅削减,同时 bundle 体积也有所下降。

适配器如何被选中:preferredAdapters 与降级保护

要理解"默认切换"在代码层面如何发生,需要看 PouchDB 的适配器注册与解析机制。当前仓库中,setup.js 展示了适配器的注册入口:

PouchDB.adapters = {};
PouchDB.preferredAdapters = [];

PouchDB.adapter = function (id, obj, addToPreferredAdapters) {
  if (obj.valid()) {
    PouchDB.adapters[id] = obj;
    if (addToPreferredAdapters) {
      PouchDB.preferredAdapters.push(id);
    }
  }
};
  • PouchDB.adapters:已注册适配器的查找表;
  • PouchDB.preferredAdapters:按优先级排序的适配器偏好列表,valid() 通过的适配器注册时追加到列表末尾;
  • PouchDB.prefix:默认为 '_pouch_',用于给本地数据库名加前缀以避免冲突。

在 6.4.2 的浏览器构建中,idb 被排在 websql 之前,因此未显式指定 opts.adapter 时,IndexedDB 自然胜出。真正决定"新建数据库用哪个适配器"的是 parseAdapter.js 中的自动选择逻辑:

if (!adapterName) { // automatically determine adapter
  for (var i = 0; i < preferredAdapters.length; ++i) {
    adapterName = preferredAdapters[i];
    // check for browsers that have been upgraded from websql-only to websql+idb
    if (adapterName === 'idb' && 'websql' in adapters &&
        hasLocalStorage() && localStorage['_pouch__websqldb_' + prefix + name]) {
      // log it, because this can be confusing during development
      guardedConsole('log', 'PouchDB is downgrading "' + name + '" to WebSQL to' +
        ' avoid data loss, because it was already opened with WebSQL.');
      continue; // keep using websql to avoid user data loss
    }
    break;
  }
}

这段代码实现了 6.4.2 最关键的兼容性保障——"降级保护"(downgrade guard):

  • 当浏览器从"仅有 WebSQL"升级为"WebSQL + IndexedDB 并存"(典型场景:Safari 老版本升级到新版本)时,如果 localStorage 中存在 _pouch__websqldb_ 前缀的数据库标记,说明该库此前是用 WebSQL 打开的;
  • 此时即便偏好列表首选 idb,PouchDB 也会跳过 idb 并继续使用 WebSQL 打开同名数据库,以避免数据丢失;
  • 开发环境下控制台会打印日志提示"PouchDB is downgrading ... to WebSQL to avoid data loss",帮助开发者理解为何没有走新的默认引擎。

这正是为什么 6.4.2 的迁移方案可以"先复制、后切换"——降级保护保证旧库在迁移完成前始终可用,而不会因为默认引擎切换而直接打不开。

面向存量用户:WebSQL → IndexedDB 复制迁移方案

发布说明明确指出:如果你在使用 PouchDB 并打算跟进新版本,就需要考虑迁移现有用户的数据。由于 6.4.2 在 Safari 中同时支持 WebSQL 与 IndexedDB,最简单的方案是用 PouchDB 自己的复制(replication)能力,在两个适配器之间搬运数据。

官方给出的 openDB 迁移封装如下(原文完整保留):

function openDB(name, opts) {
  return new Promise(function(resolve, reject) {
    var localdb = new PouchDB(name, opts);
    localdb.info().then(function(info) {

      if (info.adapter !== 'websql') {
        return resolve(localdb);
      }

      var newopts = opts || {};
      newopts.adapter = 'idb';

      var newdb = new PouchDB(name, newopts);
      var replicate = localdb.replicate.to(newdb);
      replicate.then(function() {
        resolve(newdb);
      }).catch(reject);
    }).catch(reject);
  });
}

这个函数的核心思路值得逐段拆解:

  1. 探测当前适配器:先用原有 opts 打开数据库,调用 db.info(),返回结果中的 info.adapter 会明确告诉我们是 'websql' 还是 'idb'。只有 WebSQL 才需要迁移,否则直接复用现有连接,避免无谓开销。
  2. 构造同名的 IndexedDB 数据库:复制 opts 并强制设置 adapter: 'idb',然后用同一个数据库名打开新库。由于 IndexedDB 与 WebSQL 是两套完全独立的存储,同名不会互相覆盖。
  3. 单次复制搬空全量数据:localdb.replicate.to(newdb) 将 WebSQL 库中的文档、附件、修订历史(revisions)整体复制到 IndexedDB 库。复制完成后 replicate 返回的 Promise resolve,此时 newdb 即为数据完整的新库。
  4. 错误处理:复制失败时 reject,调用方可以据此回退到 WebSQL 继续服务,或提示用户重试。

使用时的注意点:

  • opts 中若有自定义 prefix、revs_limit、auto_compaction 等配置,复制逻辑同样需要显式传入(示例中通过 newopts = opts || {} 透传);
  • 迁移期间最好引导用户停留在页面上(例如显示进度提示),因为复制在浏览器主线程内执行;
  • 迁移完成后,原 WebSQL 数据库文件仍留在浏览器存储中;如需清理,可对旧库执行 destroy(),但建议先灰度观察新库读写正常后再销毁。

验证迁移:info() 如何报告适配器

info.adapter 是迁移判断的唯一依据。从当前仓库的适配器实现看,idb 适配器在其 index.js 中维护了版本化数据库结构(ADAPTER_VERSION),并通过 indexedDB.open(dbName, ADAPTER_VERSION) 打开数据库;对 indexedDB 与 IDBKeyRange 的可用性检查(对应代码注释提到 Firefox 禁用 cookie 时会抛 SecurityError)用于 valid() 判定。这些实现细节决定了:在支持 IndexedDB 的环境里,info().adapter 会稳定返回 'idb',迁移判断才能可靠工作。

仓库中还保留了与 WebSQL 存储限额相关的压力测试页面 tests/stress/websql_storage_limit.html,以及 Node 环境下的 WebSQL 集成测试 tests/integration/test.node-websql.js,可作为迁移前后回归验证的参考。

6.4.2 的其他修复:五个值得关注的 issue

除存储引擎切换外,本次发布还包含五项具体修复,覆盖 HTTP 请求、查询引擎与存储配额等层面:

  • #7019 - 空 HTTP 请求不再崩溃:修复了空 HTTP 请求导致异常的问题,提升了对异常请求的容错;
  • #7008 - 新增 Glitch bug 辅助工具:为在 Glitch 平台上复现 bug 增加了辅助能力,方便社区反馈;
  • #6954 - 修复存储配额超限时的挂起:此前浏览器存储配额耗尽时操作可能一直挂起,本次修复了该卡死问题——对于 WebSQL/IndexedDB 这类有配额限制的本地存储,这一修复直接关系到用户体验;
  • #6958 - 修复 PouchDB find 对零值的处理:修正了 Mango 查询(pouchdb-find)中对数值 0 的查询匹配行为;
  • #6971 - 修复 allDocs 的 keys 与 limit 组合:当 allDocs({keys: [...], limit: n}) 中 limit 小于 keys.length 时,返回结果数量不正确的问题得到修复。

对于使用 allDocs 做分页、用 find 查询包含 0 值字段的文档,以及处理大附件/大数据量的应用,这五项修复都值得跟进升级。

7.0 前瞻:Promise Polyfill 与 fetch API

发布说明同时预告了 7.0 的破坏性变更方向(原文明确表示"尚未完全确定"):

  1. 移除 Promise Polyfill:PouchDB 内部自带 Promise 实现,7.0 计划改依赖环境原生 Promise。这意味着 7.0 起,运行环境必须支持原生 Promise,否则需要应用自己引入 polyfill;
  2. HTTP 请求切换到 fetch API:当前 HTTP 适配器的底层请求实现将迁移到标准 fetch,替代此前基于 XMLHttpRequest 的封装。这一改动影响所有通过 http:// / https:// 前缀连接 CouchDB 兼容服务的场景,包括 CORS 配置、鉴权头与错误处理行为。

从当前仓库看,这两个方向均已落地为现实:仓库 package.json 的版本号为 7.0.0-prerelease,依赖中已包含 node-fetch;pouchdb-core/src/setup.js 中 import { fetch } from 'pouchdb-fetch' 并暴露 PouchDB.fetch。也就是说,7.x 时代的 PouchDB 正是沿着 6.4.2 预告的路线演进的。如果你的应用运行在旧版浏览器或旧版 Node 上,升级 7.x 前务必先确认 Promise 与 fetch 的可用性。

从当前仓库看 WebSQL 的现状:插件化与共享内核

虽然 6.4.2 将 WebSQL 移出默认路径,但 WebSQL 并没有被立刻删除。当前仓库(7.0.0-prerelease)的结构清晰地展示了它的归宿:

  • 浏览器默认构建不再包含 WebSQL:pouchdb-browser/src/index.js 只注册了 pouchdb-adapter-idb、pouchdb-adapter-http、mapreduce 与 replication,WebSQL 已不在其中;
  • WebSQL 以独立插件形式存在:pouchdb/src/plugins/websql.js 头部注释写明 "this code only runs in the browser, as its own dist/ script",通过 PouchDB.plugin(WebsqlPouchPlugin) 按需挂载——需要 WebSQL 的老用户必须显式引入该插件;
  • 底层代码被抽象为共享内核:pouchdb-adapter-websql-core/README.md 说明它是 "Underlying adapter code for WebSQL and SQLite-based PouchDB adapters",即 WebSQL 与 SQLite(Node 端)适配器共用一套底层实现。这与 5.3.0 在 Node 中引入 SQLite 支持的路线一脉相承(参见 相关发布说明)。

换句话说,6.4.2 的"默认切换"只是起点,WebSQL 的最终形态是从默认构建中剥离为可选插件,实现"代码不删、默认不用、维护减负"的渐进式退役。

升级建议与验证清单

综合发布说明与源码行为,给正在使用 6.4.2 或计划升级的团队一份可执行的清单:

  1. 先验证当前适配器:在生产环境埋点统计 db.info().adapter 的分布,确认存量 WebSQL 用户比例;
  2. 在 Safari 中跑通迁移:使用上文 openDB 方案,先在测试环境验证"WebSQL → IndexedDB"复制不丢文档、不丢附件、_rev 树保持一致;
  3. 关注降级保护日志:开发阶段注意控制台中 "PouchDB is downgrading ... to WebSQL" 日志,它提示同名数据库仍由 WebSQL 管理,迁移尚未完成;
  4. 跟进 find/allDocs 修复:若业务涉及 0 值字段查询或 keys + limit 组合,建议升级到 6.4.2 并补充对应回归用例;
  5. 为 7.0 铺路:在应用层检测 window.Promise 与 window.fetch(或 globalThis.fetch),对缺失环境提前引入 polyfill,避免 7.x 升级时的兼容性断层。

结语

PouchDB 6.4.2 的发布,本质上是 PouchDB 对浏览器存储生态变迁的一次顺势而为:WebSQL 完成了它在浏览器标准化进程中的历史使命,IndexedDB 接过接力棒成为 Safari 的默认存储引擎。借助 info().adapter 探测、replicate.to() 全量复制与源码中的降级保护,存量用户可以低风险完成存储引擎迁移;而 7.0 的 Promise/fetch 路线预告,则提醒所有使用者关注运行环境的基础能力建设。存储引擎可以换,但 PouchDB "本地优先、离线可用" 的 API 承诺始终不变。

登录后查看全文
pouchdb