CKTIS / JavaScript
IndexedDB öffnen: upgradeneeded, blocked, success und error
Erkenne, ob eine IndexedDB-Öffnungsanfrage das Schema aktualisiert, auf das Schließen einer Verbindung wartet, erfolgreich war oder fehlgeschlagen ist.
Version: 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) gibt sofort einen IDBOpenDBRequest zurück, kein Promise. Das Öffnen läuft asynchron. upgradeneeded und blocked gehören zu IDBOpenDBRequest; success und error stammen von IDBRequest. Ohne version wird die vorhandene Version geöffnet oder eine Datenbank mit Version 1 angelegt. IndexedDB ist eine API der Webplattform, nicht Teil von ECMAScript. Der Zugriff hängt von der Laufzeitumgebung und den Speichereinstellungen ab.
upgradeneeded wird beim Anlegen einer Datenbank (oldVersion === 0) oder beim Anfordern einer höheren Version ausgelöst. Entscheide anhand von oldVersion und newVersion des Ereignisses, welche Migrationen nötig sind. Ändere das Schema über request.result innerhalb der aktiven versionchange-Transaktion unter request.transaction. Geh nicht davon aus, dass sie beim Warten auf unabhängige Vorgänge wie fetch() aktiv bleibt.
blocked bedeutet, dass die Upgrade-Anfrage darauf wartet, dass eine andere Verbindung zur selben Datenbank geschlossen wird. Eine bereits zum Schließen vorgemerkte Verbindung erhält kein versionchange mehr, kann das Upgrade aber bis zum Abschluss ihrer Transaktionen verzögern. Behandle in der Anwendung versionchange an der bestehenden IDBDatabase-Verbindung und rufe dort close() auf. Nutze blocked, um über den Grund der Wartezeit zu informieren. Die Anfrage muss nicht erneut gestellt werden.
success bedeutet, dass request.result die offene IDBDatabase-Verbindung enthält. Falls eine Migration nötig war, wurde ihre Transaktion bereits festgeschrieben. Beim Öffnen der aktuellen Version wird upgradeneeded nicht ausgelöst. Erfolgreiches Öffnen garantiert nicht, dass spätere Transaktionen gelingen.
error bedeutet, dass die Anfrage fehlgeschlagen ist. Lies die DOMException aus request.error. Eine niedrigere als die gespeicherte Version führt zu VersionError; ein Abbruch der Upgrade-Transaktion macht ihre Änderungen rückgängig und lässt das Öffnen scheitern. Einen synchronen Fehler wie TypeError bei Version 0 wirft open() direkt, ohne ein error-Ereignis auszulösen.
Beispiele
<!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>Ergebnis
upgradeneeded: 0 -> 1 success: 1 blocked: 2 upgradeneeded: 1 -> 2 success: 2 error: VersionError
Öffne die HTML-Seite über HTTPS oder von localhost in einem Browser, in dem IndexedDB und `crypto.randomUUID()` verfügbar sind. Die Verbindung zu Version `1` bleibt absichtlich bis `blocked` offen. Nach dem Schließen öffnet dieselbe Anfrage Version `2`. Eine weitere Anfrage für Version `1` scheitert mit `VersionError`.
Zugehörige Lektionen
- JavaScript · Lektion 20 · Mittlere Stufe · Version: 3
- JavaScript · Lektion 21 · Mittlere Stufe · Version: 3
Quellen
- 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