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

CKTIS / JavaScript

IDBOpenDBRequest — abrir e atualizar uma base de dados IndexedDB

IDBOpenDBRequest representa um pedido assíncrono para abrir ou eliminar uma base de dados IndexedDB. Os eventos permitem gerir atualizações do esquema, bloqueios causados por outras ligações e a conclusão da operação. Não é uma ligação à base de dados nem uma Promise.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

const request = indexedDB.open(name, version);
request.onupgradeneeded = (event) => { /* migrate schema */ };
request.addEventListener("blocked", handler);
request.addEventListener("success", handler);
request.addEventListener("error", handler);
// request.transaction: upgrade IDBTransaction or null

IDBOpenDBRequest é devolvido imediatamente por indexedDB.open(name, version) e indexedDB.deleteDatabase(name). Herda de IDBRequest e, depois, de EventTarget; obtém o resultado através de eventos, não com await request. É uma API Web do navegador da família IndexedDB, não uma funcionalidade ECMAScript. Segundo a MDN, a interface está amplamente disponível desde julho de 2015. A MDN indica separadamente que a interface está disponível em Web Workers; essa data não indica desde quando o suporte em Web Workers é generalizado entre os navegadores. A presença de Node 24 num repositório não comprova o suporte desta API.

IDBOpenDBRequest.upgradeneeded designa o evento upgradeneeded, não um método. É acionado ao criar uma base de dados ou ao abri-la com uma versão superior. IDBOpenDBRequest.onupgradeneeded é a propriedade à qual atribuis o respetivo controlador; em alternativa, podes usar addEventListener("upgradeneeded", handler). É aqui que crias ou alteras object stores e índices. A propriedade herdada IDBOpenDBRequest.transaction expõe a transação de atualização no modo versionchange; sem atualização, o valor é null. Não representa uma transação de dados posterior qualquer.

IDBOpenDBRequest.blocked designa o evento blocked: outra ligação aberta impede a atualização ou eliminação da base de dados. Trata-se de uma situação de espera, não de uma falha definitiva. Trata versionchange em cada ligação, fechando-a com db.close(), e informa o utilizador sobre o bloqueio. Um controlador blocked, por si só, não fecha outras ligações.

IDBOpenDBRequest.success e IDBOpenDBRequest.error designam eventos herdados de IDBRequest, também tratados através de onsuccess e onerror. Após a abertura bem-sucedida, request.result contém um IDBDatabase; após a eliminação, o valor é undefined. A abertura só é bem-sucedida depois de confirmada qualquer atualização necessária; upgradeneeded ainda não significa sucesso. Em caso de erro, consulta request.error. Não leias o resultado imediatamente após open(); trata as falhas assíncronas através de error, separadamente das exceções síncronas lançadas pela própria chamada.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IDBOpenDBRequest: opening and upgrading a database</title>
</head>
<body>
  <h1>Opening and upgrading an IndexedDB database</h1>
  <script>
    (() => {
      const name = 'cktis-open-' + crypto.getRandomValues(new Uint32Array(4)).join('-');
      const report = error => console.log(error.name === 'SecurityError'
        ? 'IndexedDB unavailable: SecurityError' : `IndexedDB error: ${error.name}`);
      let factory, opening;
      try {
        factory = window.indexedDB;
        if (!factory) {
          console.log('IndexedDB unavailable: API missing');
          return;
        }
        opening = factory.open(name, 1);
      } catch (error) {
        report(error);
        return;
      }
      let created = false;
      opening.onerror = () => report(opening.error);
      opening.onupgradeneeded = () => {
        created = true;
        opening.result.createObjectStore('notes', { keyPath: 'id' });
      };
      opening.onsuccess = () => {
        const first = opening.result;
        if (!created) {
          first.close();
          console.log('Fixture name already in use');
          return;
        }
        // Hold the old connection open until the new request reports that it is blocked.
        const upgrade = factory.open(name, 2);
        upgrade.onblocked = event => {
          console.log(`blocked: ${event.oldVersion} -> ${event.newVersion}`);
          first.close();
        };
        upgrade.onupgradeneeded = () => {
          upgrade.result.createObjectStore('labels');
          console.log(`upgrade: ${upgrade.transaction.mode}`);
        };
        upgrade.onerror = () => {
          first.close();
          report(upgrade.error);
          factory.deleteDatabase(name);
        };
        upgrade.onsuccess = () => {
          const db = upgrade.result;
          console.log(`open: ${db.version}, labels: ${db.objectStoreNames.contains('labels')}`);
          db.close();
          const deletion = factory.deleteDatabase(name);
          deletion.onerror = () => report(deletion.error);
          deletion.onsuccess = event => console.log(`deleted version: ${event.oldVersion}`);
        };
      };
    })();
  </script>
</body>
</html>

Resultado

Observed in the isolated run (IndexedDB access denied):
IndexedDB unavailable: SecurityError

Expected on a successful run with IndexedDB access:
blocked: 1 -> 2
upgrade: versionchange
open: 2, labels: true
deleted version: 2

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes