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
- IDBOpenDBRequest
- IDBFactory: open() method
- IDBOpenDBRequest: upgradeneeded event
- IDBOpenDBRequest: blocked event
- IDBRequest: success event
- IDBRequest: error event
- IDBRequest: error property
- IDBRequest: transaction property
- IDBVersionChangeEvent
- IDBDatabase: versionchange event
- Using IndexedDB
- Crypto: randomUUID() method