CKTIS / JavaScript
IndexedDB openen: upgradeneeded, blocked, success en error
Herken wanneer een verzoek om IndexedDB te openen een schemawijziging nodig heeft, op een verbinding wacht, slaagt of mislukt.
Versie: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
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) retourneert meteen een IDBOpenDBRequest, geen Promise. Het openen gebeurt asynchroon. upgradeneeded en blocked horen bij IDBOpenDBRequest; success en error zijn geërfd van IDBRequest. Laat je version weg, dan wordt de bestaande versie geopend of een database met versie 1 aangemaakt. IndexedDB is een webplatform-API, geen onderdeel van ECMAScript; toegang hangt af van de uitvoeringsomgeving en opslaginstellingen.
upgradeneeded treedt op als de database wordt aangemaakt (oldVersion === 0) of als je een hogere versie aanvraagt. Bepaal met oldVersion en newVersion van de gebeurtenis welke migraties nodig zijn. Wijzig het schema via request.result binnen de actieve versionchange-transactie in request.transaction. Ga er niet van uit dat die actief blijft terwijl je wacht op een losstaande bewerking zoals fetch().
blocked betekent dat het upgradeverzoek wacht tot een andere verbinding met dezelfde database is gesloten. IndexedDB stuurt geen versionchange naar een verbinding die al bezig is met sluiten, maar die verbinding kan de upgrade nog ophouden tot haar transacties klaar zijn. Handel in een app versionchange af op de bestaande IDBDatabase-verbinding en roep daarop close() aan. Gebruik blocked om de gebruiker te vertellen waarom het openen nog niet klaar is. Je hoeft het verzoek niet opnieuw te doen.
success betekent dat request.result de geopende IDBDatabase-verbinding bevat. Was een upgrade nodig, dan is die transactie al vastgelegd. Openen op de huidige versie veroorzaakt geen upgradeneeded. Een geslaagde opening garandeert niet dat latere transacties slagen.
error betekent dat het verzoek is mislukt. Lees de DOMException uit request.error. Een versie lager dan de opgeslagen versie geeft VersionError; afbreken van de upgradetransactie draait de wijzigingen terug en laat het openen mislukken. Een synchrone fout, zoals TypeError bij versie 0, wordt rechtstreeks door open() gegooid, zonder error-gebeurtenis.
Voorbeelden
<!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>Resultaat
upgradeneeded: 0 -> 1 success: 1 blocked: 2 upgradeneeded: 1 -> 2 success: 2 error: VersionError
Open de HTML-pagina via HTTPS of vanaf localhost in een browser waarin IndexedDB en `crypto.randomUUID()` beschikbaar zijn. De verbinding met versie `1` blijft opzettelijk open tot `blocked`. Na het sluiten opent hetzelfde verzoek versie `2`. Het volgende verzoek om versie `1` mislukt met `VersionError`.
Gerelateerde lessen
- JavaScript · Les 20 · Gemiddeld · Versie: 3
- JavaScript · Les 21 · Gemiddeld · Versie: 3
Bronnen
- 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