Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Apertura de IndexedDB: upgradeneeded, blocked, success y error

Distingue si una solicitud de apertura de IndexedDB debe actualizar el esquema, espera el cierre de una conexión, se ha completado o ha fallado.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

const request = indexedDB.open(name); // or indexedDB.open(name, version)
request.addEventListener("upgradeneeded", onUpgradeNeeded);
request.addEventListener("blocked", onBlocked);
request.addEventListener("success", onSuccess);
request.addEventListener("error", onError);

// Alternatively, assign one handler to each property:
request.onupgradeneeded = onUpgradeNeeded;
request.onblocked = onBlocked;
request.onsuccess = onSuccess;
request.onerror = onError;

indexedDB.open(name, version) devuelve de inmediato un IDBOpenDBRequest, no una Promise. La apertura es asíncrona. upgradeneeded y blocked son propios de IDBOpenDBRequest; success y error se heredan de IDBRequest. Si omites version, se abre la versión existente o se crea una base en la versión 1. IndexedDB es una API de la plataforma web, no de ECMAScript; el acceso depende del entorno de ejecución y de la configuración de almacenamiento.

upgradeneeded se dispara al crear la base (oldVersion === 0) o al pedir una versión superior. Usa oldVersion y newVersion del evento para decidir qué migraciones ejecutar. Cambia el esquema mediante request.result dentro de la transacción versionchange activa, accesible en request.transaction. No des por hecho que seguirá activa mientras esperas una operación ajena, como fetch().

blocked indica que la solicitud de actualización espera a que se cierre otra conexión a la misma base. IndexedDB no envía versionchange a una conexión cuyo cierre ya está pendiente, pero esa conexión aún puede retrasar la actualización hasta que terminen sus transacciones. En una aplicación, gestiona versionchange en la conexión IDBDatabase existente y llama allí a close(). Usa blocked para explicar al usuario por qué la apertura sigue pendiente. No hace falta repetir la solicitud.

success indica que request.result contiene la conexión IDBDatabase abierta. Si hubo una actualización, su transacción ya se ha confirmado. Abrir la versión actual no dispara upgradeneeded. Una apertura correcta no garantiza el éxito de transacciones posteriores.

error indica que la solicitud ha fallado. Lee la DOMException en request.error. Pedir una versión inferior a la almacenada produce VersionError; abortar la transacción de actualización revierte sus cambios y hace fallar la apertura. Un error síncrono, como TypeError para la versión 0, lo lanza directamente open() sin disparar un evento error.

Ejemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IndexedDB open request events</title>
</head>
<body>
  <pre id="output"></pre>
  <script>
    (async () => {
      const { indexedDB, crypto } = window;
      const output = document.getElementById("output");
      const name = `ck-tis-idb-${crypto.randomUUID()}`;

      function log(line) {
        output.textContent += (output.textContent ? "\n" : "") + line;
        console.log(line);
      }

      function open(version, releaseBlocker) {
        return new Promise((resolve, reject) => {
          const request = indexedDB.open(name, version);
          request.onupgradeneeded = ({ oldVersion, newVersion }) => {
            log(`upgradeneeded: ${oldVersion} -> ${newVersion}`);
            const db = request.result;
            if (oldVersion < 1) db.createObjectStore("notes");
            if (oldVersion < 2 && newVersion >= 2) db.createObjectStore("tags");
          };
          request.onblocked = () => {
            log(`blocked: ${version}`);
            releaseBlocker?.();
          };
          request.onsuccess = () => {
            log(`success: ${request.result.version}`);
            resolve(request.result);
          };
          request.onerror = () => reject(request.error);
        });
      }

      let first;
      let second;
      try {
        first = await open(1);
        // Intentionally keep version 1 open until the next request is blocked.
        second = await open(2, () => first.close());
        try {
          const unexpected = await open(1);
          unexpected.close();
          throw new Error("Expected VersionError");
        } catch (error) {
          if (error.name !== "VersionError") throw error;
          log(`error: ${error.name}`);
        }
      } finally {
        first?.close();
        second?.close();
        const cleanup = indexedDB.deleteDatabase(name);
        cleanup.onerror = () => console.error(cleanup.error);
      }
    })().catch((error) => console.error(error));
  </script>
</body>
</html>

Resultado

upgradeneeded: 0 -> 1
success: 1
blocked: 2
upgradeneeded: 1 -> 2
success: 2
error: VersionError

Abre la página HTML por HTTPS o desde localhost en un navegador con IndexedDB y `crypto.randomUUID()` disponibles. La conexión a la versión `1` se mantiene abierta a propósito hasta `blocked`. Al cerrarla, la misma solicitud abre la versión `2`. La siguiente solicitud de la versión `1` falla con `VersionError`.

Lecciones relacionadas

  • JavaScript · Lección 20 · Intermedio · Versión: 3
  • JavaScript · Lección 21 · Intermedio · Versión: 3

Fuentes