CKTIS / JavaScript
IDBOpenDBRequest — Öffnen und Aktualisieren einer IndexedDB-Datenbank
IDBOpenDBRequest steht für eine asynchrone Anfrage zum Öffnen oder Löschen einer IndexedDB-Datenbank. Über Ereignisse lassen sich Schemaaktualisierungen, Blockierungen durch andere Verbindungen und der Abschluss des Vorgangs behandeln. Das Objekt ist weder eine Datenbankverbindung noch ein Promise.
Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntax
const request = indexedDB.open(name, version);
request.onupgradeneeded = (event) => { /* migrate schema */ };
request.addEventListener("blocked", handler);
request.addEventListener("success", handler);
request.addEventListener("error", handler);
// request.transaction: upgrade IDBTransaction or nullIDBOpenDBRequest wird sofort von indexedDB.open(name, version) und indexedDB.deleteDatabase(name) zurückgegeben. Es erbt von IDBRequest und anschließend von EventTarget; das Ergebnis erhältst du über Ereignisse, nicht mit await request. Dies ist eine browserbasierte Web API aus der IndexedDB-Familie, kein ECMAScript-Feature. Laut MDN ist die Schnittstelle seit Juli 2015 breit verfügbar. MDN weist gesondert darauf hin, dass die Schnittstelle in Web Workers verfügbar ist. Aus dem genannten Datum geht nicht hervor, seit wann Browser die Schnittstelle in Web Workers auf breiter Basis unterstützen. Node 24 in einem Repository belegt nicht die Unterstützung dieser API.
IDBOpenDBRequest.upgradeneeded bezeichnet das Ereignis upgradeneeded, keine Methode. Es wird beim Erstellen einer Datenbank oder beim Öffnen mit einer höheren Version ausgelöst. IDBOpenDBRequest.onupgradeneeded ist die Eigenschaft zum Zuweisen des Handlers; alternativ kannst du addEventListener("upgradeneeded", handler) verwenden. Hier erstellst oder änderst du Object Stores und Indizes. Die geerbte Eigenschaft IDBOpenDBRequest.transaction stellt die Upgrade-Transaktion im Modus versionchange bereit; ohne Upgrade ist sie null. Sie steht nicht für eine beliebige spätere Datentransaktion.
IDBOpenDBRequest.blocked bezeichnet das Ereignis blocked: Eine andere offene Verbindung verhindert ein Upgrade oder das Löschen der Datenbank. Das ist ein Wartezustand, kein endgültiger Fehler. Behandle versionchange an jeder Verbindung, indem du sie mit db.close() schließt, und informiere den Benutzer über die Blockierung. Ein blocked-Handler allein schließt keine anderen Verbindungen.
IDBOpenDBRequest.success und IDBOpenDBRequest.error bezeichnen von IDBRequest geerbte Ereignisse, die auch über onsuccess und onerror behandelt werden. Nach erfolgreichem Öffnen enthält request.result ein IDBDatabase; nach dem Löschen ist es undefined. Das Öffnen ist erst erfolgreich, wenn ein erforderliches Upgrade abgeschlossen ist; upgradeneeded bedeutet noch keinen Erfolg. Prüfe bei einem Fehler request.error. Lies das Ergebnis nicht unmittelbar nach open() aus; behandle asynchrone Fehler über error, getrennt von synchronen Ausnahmen des Aufrufs selbst.
Beispiele
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IDBOpenDBRequest: opening and upgrading a database</title>
</head>
<body>
<h1>Opening and upgrading an IndexedDB database</h1>
<script>
(() => {
const name = 'cktis-open-' + crypto.getRandomValues(new Uint32Array(4)).join('-');
const report = error => console.log(error.name === 'SecurityError'
? 'IndexedDB unavailable: SecurityError' : `IndexedDB error: ${error.name}`);
let factory, opening;
try {
factory = window.indexedDB;
if (!factory) {
console.log('IndexedDB unavailable: API missing');
return;
}
opening = factory.open(name, 1);
} catch (error) {
report(error);
return;
}
let created = false;
opening.onerror = () => report(opening.error);
opening.onupgradeneeded = () => {
created = true;
opening.result.createObjectStore('notes', { keyPath: 'id' });
};
opening.onsuccess = () => {
const first = opening.result;
if (!created) {
first.close();
console.log('Fixture name already in use');
return;
}
// Hold the old connection open until the new request reports that it is blocked.
const upgrade = factory.open(name, 2);
upgrade.onblocked = event => {
console.log(`blocked: ${event.oldVersion} -> ${event.newVersion}`);
first.close();
};
upgrade.onupgradeneeded = () => {
upgrade.result.createObjectStore('labels');
console.log(`upgrade: ${upgrade.transaction.mode}`);
};
upgrade.onerror = () => {
first.close();
report(upgrade.error);
factory.deleteDatabase(name);
};
upgrade.onsuccess = () => {
const db = upgrade.result;
console.log(`open: ${db.version}, labels: ${db.objectStoreNames.contains('labels')}`);
db.close();
const deletion = factory.deleteDatabase(name);
deletion.onerror = () => report(deletion.error);
deletion.onsuccess = event => console.log(`deleted version: ${event.oldVersion}`);
};
};
})();
</script>
</body>
</html>Ergebnis
Observed in the isolated run (IndexedDB access denied): IndexedDB unavailable: SecurityError Expected on a successful run with IndexedDB access: blocked: 1 -> 2 upgrade: versionchange open: 2, labels: true deleted version: 2
Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.