CKTIS / JavaScript
IndexedDB: onupgradeneeded e a transação de atualização
Altera o esquema do IndexedDB em `onupgradeneeded`, obtém a transação com `request.transaction` e espera por `success` antes de usar o novo esquema.
Versão: Current web platform; runtime support varies
Sintaxe
// The upgrade lifecycle is defined by IndexedDB, not by an ECMAScript edition.
const request = indexedDB.open(name, version);
request.onupgradeneeded = (event) => {
const db = request.result;
const tx = request.transaction;
// Apply schema changes through db and tx while tx is active.
};indexedDB.open(name, version) devolve imediatamente um IDBOpenDBRequest; a abertura decorre de forma assíncrona. onupgradeneeded é a propriedade que recebe o manipulador do evento upgradeneeded. O evento é disparado ao criar uma base de dados ou ao abri-la com uma versão superior. Com a mesma versão não é disparado; uma versão inferior causa VersionError. IndexedDB é uma API Web, não uma funcionalidade do ECMAScript 2024.
No manipulador, request.result contém a ligação IDBDatabase. A propriedade só de leitura request.transaction, herdada de IDBRequest, contém a IDBTransaction que o IndexedDB cria automaticamente no modo "versionchange". O seu valor é null imediatamente após open() e novamente em success. db.transaction() inicia uma transação separada no modo "readonly" ou "readwrite", não uma transação de atualização.
Usa event.oldVersion e event.newVersion para escolher os passos da migração. Numa base nova, oldVersion vale 0; verificações de versão independentes permitem executar vários passos quando se saltam versões intermédias. Cria um repositório de objetos com db.createObjectStore() e acrescenta um índice a um repositório existente com tx.objectStore(name).createIndex(). Também podes migrar registos na mesma transação.
Coloca as operações em fila enquanto a transação estiver ativa: diretamente no manipulador de upgradeneeded ou nos manipuladores de eventos dos seus pedidos. Não partas do princípio de que continua ativa depois de await fetch() ou quando se executa a função de um temporizador. tx.abort() reverte as alterações ao esquema, aos dados e à versão; o pedido de abertura emite error em vez de success. Se a transação for confirmada, o seu complete ocorre antes do success do pedido de abertura.
Uma ligação existente, por exemplo noutro separador, pode atrasar a atualização. Trata blocked no pedido de abertura e fecha as ligações existentes com db.close() nos respetivos manipuladores de versionchange.
Exemplos
<!doctype html>
<meta charset="utf-8">
<title>IndexedDB upgrade transaction</title>
<script>
(() => {
const name = `cktis-indexeddb-${crypto.randomUUID()}`;
const reportError = (event) => console.error(event.target.error);
function openVersion(version) {
const request = indexedDB.open(name, version);
request.onerror = reportError;
request.onupgradeneeded = ({ oldVersion, newVersion }) => {
const db = request.result;
const tx = request.transaction;
if (oldVersion < 1) db.createObjectStore("books", { keyPath: "id" });
if (oldVersion < 2 && newVersion >= 2) {
console.log(`upgrade: ${oldVersion} -> ${newVersion} (${tx.mode})`);
tx.objectStore("books").createIndex("by_title", "title");
tx.oncomplete = () => console.log("complete");
}
};
return request;
}
const first = openVersion(1);
first.onsuccess = () => {
first.result.close();
const second = openVersion(2);
console.log(`before: ${second.transaction}`);
second.onsuccess = () => {
const db = second.result;
const store = db.transaction("books", "readonly").objectStore("books");
console.log(`success: ${second.transaction}; index: ${store.indexNames.contains("by_title")}`);
db.close();
indexedDB.deleteDatabase(name).onerror = reportError;
};
};
})();
</script>Resultado
before: null upgrade: 1 -> 2 (versionchange) complete success: null; index: true
Abre a página HTML no navegador, num contexto seguro com acesso a IndexedDB e a `crypto.randomUUID()`. Consulta o resultado na consola de desenvolvimento. O exemplo cria uma base de dados com nome aleatório na versão 1, fecha a ligação, acrescenta `by_title` na versão 2 e pede a eliminação da base de teste depois de verificar o índice.
Lições relacionadas
- JavaScript · Lição 31 · Avançado · Versão: 4
Fontes
- IDBOpenDBRequest: upgradeneeded event
- IDBRequest: transaction property
- IDBFactory: open() method
- IDBRequest: error property
- IDBTransaction
- IDBDatabase: transaction() method
- Using IndexedDB
- IDBOpenDBRequest: blocked event
- IDBDatabase: versionchange event
- IDBObjectStore: createIndex() method
- Crypto: randomUUID() method
- IDBFactory: deleteDatabase() method