Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Abertura de IndexedDB: upgradeneeded, blocked, success e error

Distingue quando um pedido de abertura do IndexedDB precisa de atualizar o esquema, aguarda o fecho de uma ligação, tem êxito ou falha.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

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) devolve de imediato um IDBOpenDBRequest, não uma Promise. A abertura é assíncrona. upgradeneeded e blocked pertencem a IDBOpenDBRequest; success e error são herdados de IDBRequest. Se omitires version, é aberta a versão existente ou é criada uma base de dados na versão 1. IndexedDB é uma API da plataforma Web, não de ECMAScript; o acesso depende do ambiente de execução e das definições de armazenamento.

upgradeneeded é emitido ao criar a base de dados (oldVersion === 0) ou ao pedir uma versão superior. Usa oldVersion e newVersion do evento para escolher as migrações a executar. Altera o esquema através de request.result na transação versionchange ativa, acessível em request.transaction. Não pressuponhas que esta continua ativa enquanto aguardas uma operação independente como fetch().

blocked indica que o pedido de atualização aguarda o fecho de outra ligação à mesma base de dados. O IndexedDB não envia versionchange a uma ligação cujo fecho já está pendente, mas essa ligação ainda pode atrasar a atualização até as suas transações terminarem. Numa aplicação, trata versionchange na ligação IDBDatabase existente e chama close() nessa ligação. Usa blocked para explicar a espera ao utilizador. Não é preciso repetir o pedido.

success significa que request.result contém a ligação IDBDatabase aberta. Se foi necessária uma atualização, a respetiva transação já foi confirmada. Abrir a versão atual não emite upgradeneeded. Uma abertura bem-sucedida não garante que as transações posteriores tenham êxito.

error significa que o pedido falhou. Lê a DOMException em request.error. Pedir uma versão inferior à que está armazenada produz VersionError; abortar a transação de atualização reverte as suas alterações e faz falhar a abertura. Um erro síncrono, como TypeError para a versão 0, é lançado diretamente por open() sem emitir um evento error.

Exemplos

<!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 a página HTML por HTTPS ou a partir de localhost num navegador com IndexedDB e `crypto.randomUUID()` disponíveis. A ligação à versão `1` é mantida aberta de propósito até `blocked`. Ao fechá-la, o mesmo pedido abre a versão `2`. O pedido seguinte da versão `1` falha com `VersionError`.

Lições relacionadas

  • JavaScript · Lição 20 · Intermédio · Versão: 3
  • JavaScript · Lição 21 · Intermédio · Versão: 3

Fontes