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

CKTIS / JavaScript

IDBDatabase — uma ligação a uma base de dados IndexedDB

IDBDatabase representa uma ligação aberta a uma base de dados IndexedDB. Permite criar armazenamentos durante atualizações do esquema, iniciar transações e fechar a ligação.

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);
// In upgradeneeded:
const store = request.result.createObjectStore(storeName, options);
// After open succeeds:
const db = request.result;
db.objectStoreNames;
const tx = db.transaction(storeNames, "readonly");
db.onversionchange = () => db.close();

Obtém um IDBDatabase em request.result quando indexedDB.open() é bem-sucedido. Trata-se de uma API Web, não de uma parte de ECMAScript; o Node 24 não comprova o suporte nos navegadores. Verifica se indexedDB está disponível no ambiente de destino; as especificações citadas não são tabelas de compatibilidade dos navegadores.

IDBDatabase.createObjectStore() só funciona dentro de uma transação de atualização ativa, geralmente em upgradeneeded. IDBDatabase.objectStoreNames devolve uma DOMStringList ordenada de nomes, não um array. Se necessário, utiliza .contains() antes de criar um armazenamento.

IDBDatabase.transaction() especifica o âmbito dos armazenamentos e o modo: readonly por predefinição ou readwrite. Não permite criar manualmente uma transação versionchange. Coloca as operações em fila enquanto a transação estiver ativa; não assumas que se mantém ativa após chamadas await arbitrárias. O sucesso de um pedido não significa que a transação tenha sido confirmada: aguarda por complete da transação.

Em resposta a um pedido para abrir a base de dados com um número de versão superior ou para a eliminar, o IndexedDB envia o evento IDBDatabase.versionchange às ligações existentes à base de dados, exceto às que têm o indicador close pending ativo. Essas ligações não recebem o evento, mesmo que permaneçam abertas até terminarem as transações em curso. Não é necessário ter uma ligação aberta para fazer o pedido, e um pedido de eliminação não abre nenhuma ligação. Trata o evento com onversionchange. É distinto de upgradeneeded. IDBDatabase.close() impede novas transações e fecha a ligação depois de as existentes terminarem, sem eliminar dados. As ligações deixadas abertas podem bloquear atualizações.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Using an IDBDatabase connection</title>
</head>
<body>
<script>
  (() => {
    const name = `cktis-connection-${Date.now()}-${Math.random()}`;
    const unavailable = () => console.log('IndexedDB unavailable in this context.');
    let open;
    try {
      // Opening a connection requires a context that permits IndexedDB.
      open = indexedDB.open(name, 1);
    } catch {
      unavailable();
      return;
    }
    open.onerror = unavailable;
    open.onupgradeneeded = () => {
      open.result.createObjectStore('notes', { keyPath: 'id' });
    };
    open.onsuccess = () => {
      const db = open.result;
      const tx = db.transaction('notes', 'readwrite');
      const store = tx.objectStore('notes');
      store.put({ id: 1, text: 'Hello' });
      const read = store.get(1);
      function cleanup() {
        db.close();
        indexedDB.deleteDatabase(name);
      }
      tx.oncomplete = () => {
        console.log(read.result.text);
        cleanup();
      };
      tx.onabort = () => {
        cleanup();
        console.log('Database transaction aborted.');
      };
    };
  })();
</script>
</body>
</html>

Resultado

Hello

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