IndexedDB onupgradeneeded 怎样迁移对象仓库

IndexedDB 迁移对象仓库，要先提高 indexedDB.open(name, version) 的数据库版本，再在 onupgradeneeded 中使用浏览器提供的升级事务完成仓库、索引和旧记录变更。通过 event.oldVersion 决定哪些迁移尚未执行，等打开请求的 onsuccess 到来后，业务代码再使用新结构。

下面用任务仓库从版本 1 升到版本 2 的例子说明：保留以 id 为主键的 tasks，给缺少状态的记录补 status，并新增 by_status 索引。我会优先选择这种增量迁移，避免为了增加查询能力删除原仓库。这里的版本是示例应用自己的数据库版本，不是某次浏览器新功能发布。

Web API 文档地址：https://developer.mozilla.org/en-US/docs/Web/API

版本变化：任务仓库增加状态查询

IndexedDB 的记录不像固定列关系表，普通字段可随对象一起保存；提高数据库版本不是为了“增加一列”本身，而是为了组织新索引及旧数据的统一迁移。只改新写入代码，不会自动给历史记录补上 status，查询索引时也不能假设所有旧记录都已有状态。

为什么结构变更必须使用升级事务

创建对象仓库及相关结构变更需要 versionchange 事务。onupgradeneeded 触发时，request.result 是数据库句柄，request.transaction 是当前升级事务。已有仓库应通过这个事务的 objectStore 取得，不要再新建普通 readwrite 事务来代替升级事务。

事务只在规定的活动时段允许排队请求。把升级处理器改成 async 并等待 fetch、定时器或用户操作，可能在恢复执行前就让事务变为非活动或结束。数据库请求自身的 success 回调可以继续发起该事务中的请求，因此示例用游标回调逐条更新。

升级事务把这次结构与数据修改纳入同一原子范围，失败中止时应保留旧版本可用状态。不要给写入失败随意调用 preventDefault 以压掉错误，否则可能把数据不完整的情况当成可继续提交。

对旧数据的影响与完整迁移代码

这段代码假定版本 1 的 tasks 已以 id 为内联主键、记录是普通任务对象，且没有 by_status 索引。首次安装的 oldVersion 为 0，也会执行两个独立版本分支；不能写成互斥的 if/else if，否则可能漏掉新用户需要的后续结构。

function openTaskDatabase() {
  return new Promise((resolve, reject) => {
    // 这是应用数据库版本，不是浏览器或 IndexedDB API 版本
    const request = indexedDB.open("task-notebook-demo", 2);
    let migrationError = null;
    request.onblocked = () => {
      console.warn("请关闭仍使用此数据库的旧页面，升级正在等待");
    };
    request.onerror = () => reject(migrationError ?? request.error);
    request.onupgradeneeded = (event) => {
      const db = request.result;
      const tx = request.transaction;
      const fail = (error) => {
        migrationError = error;
        tx.abort();
      };
      try {
        // 独立条件支持首次安装直接经过所有历史版本
        if (event.oldVersion  {
            const cursor = scan.result;
            if (!cursor) return;
            try {
              const row = cursor.value;
              if (!row || typeof row !== "object" || Array.isArray(row)) {
                throw new TypeError("任务记录不是预期对象");
              }
              // 保留已有字符串状态；只为旧记录补上默认状态
              if (typeof row.status !== "string") {
                row.status = "pending";
                cursor.update(row);
              }
              // 在 IndexedDB 请求回调中继续排队，不等待网络请求
              cursor.continue();
            } catch (error) {
              fail(error);
            }
          };
          // 请求错误保留默认冒泡行为，使升级事务中止
        }
      } catch (error) {
        fail(error);
      }
    };
    request.onsuccess = () => {
      const db = request.result;
      db.onversionchange = () => {
        // 后续其他页面升级时释放连接；业务层还需停止使用旧句柄
        db.close();
        console.warn("数据库版本发生变化，请刷新页面");
      };
      resolve(db);
    };
  });
}

status 的默认值 pending 是示例业务规则，不是 IndexedDB 内置状态。代码保留已有字符串状态，原始 id 和其他字段也继续保留。新增索引后，在同一事务中更新记录，相应索引内容会随之维护。

这里不通过“仓库是否存在”猜历史版本：迁移代码已经声明了版本 1 的结构契约。如果实际历史版本使用不同仓库名、键路径或记录形状，应据真实历史设计迁移分支。遇到异常对象时示例中止升级，没有为了凑齐字段而丢弃数据。

同步异常会被捕获并主动 abort；异步数据库请求失败保留默认错误传播，使升级失败回到打开请求的 error。游标扫描结束只说明不再有下一条记录，不代表全部修改已提交；应用取得可用连接的时点仍是打开请求的 success。

旧标签页连接与部署建议

另一个标签页或 Worker 持有旧数据库连接时，新版本打开请求可能进入 blocked。此时请求仍在等待，不能把 blocked 简单解释为数据库损坏，更不能通过删除用户数据库解决。已有连接应监听 versionchange，停止继续创建业务事务并关闭句柄，页面再提示用户刷新。

示例的 versionchange 回调关闭连接并提醒刷新；完整应用还要禁用使用旧句柄的入口，处理已开始的业务事务和未保存表单。close 不等于立即取消所有正在进行的事务，因此升级等待可能还会持续片刻。旧页面若根本没有监听机制，只能引导关闭相关页面，不能假装新页面能强制接管连接。

我会把版本号与迁移代码一起发布，并让业务读写在打开 Promise 成功后开始。回滚前端代码也不会自动降低已经升级的数据库版本；旧代码显式以较低版本打开时可能收到 VersionError，应提前设计兼容读取或后续迁移，而不是调回版本号。

keyPath 是只读配置，不能直接把原仓库的 id 改成另一个键路径。确需更换主键时，应另建目标仓库、转换并复制记录，考虑键冲突及错误中止，再安排旧仓库退场。该操作与本文保留主键、补字段和加索引不同，不要用 deleteObjectStore 后空建仓库替代数据迁移。

最小使用与结果判断

把下面代码放在前一个函数之后，在应用自己的同源页面中调用。它用新索引统计 pending 记录，并等读取事务 complete 后返回。空库中的数量为零是正常情况；这个查询不会给新库自动生成示例任务。

function countPending(db) {
  return new Promise((resolve, reject) => {
    const tx = db.transaction("tasks", "readonly");
    const count = tx.objectStore("tasks").index("by_status").count("pending");
    let total = 0;
    count.onsuccess = () => { total = count.result; };
    // 等整个事务完成，再向调用者报告成功
    tx.oncomplete = () => resolve(total);
    tx.onabort = () => reject(tx.error ?? new Error("查询事务中止"));
  });
}

async function showPendingCount() {
  const db = await openTaskDatabase();
  try {
    console.log("待处理任务数", await countPending(db));
  } finally {
    // 这个一次性示例查询后即关闭；常驻应用自行管理连接生命周期
    db.close();
  }
}
showPendingCount().catch(console.error);

这些是读者可复现的判断条件，不是本文的实测报告。验证旧库升级时要保留与真实版本 1 相同的结构和代表性记录；仅在全新空库里看见索引，不能证明旧数据迁移正确。大量历史记录需要额外评估升级等待时间；适合采用结构升级加后续可恢复数据回填的场景，应另外设计状态和兼容读写规则。

为什么每次刷新没有触发 onupgradeneeded？

只有首次建库或请求更高数据库版本时才需要升级。已有版本与请求版本相同，正常打开不会再次执行迁移。

cursor.update 成功就能显示迁移完成吗？

不能。单条请求成功不等于整个升级事务完成，后面的请求仍可能失败。应等数据库打开 success 后再初始化新版本业务。

为什么不在升级回调里先下载字段映射？

等待网络会脱离事务活动时段。需要外部映射时应在打开升级前准备好，或设计独立的后续数据迁移任务，并明确新旧格式兼容规则。

参考：IndexedDB 升级事务规范、MDN upgradeneeded、MDN versionchange。