Signatur
Beschreibung
Der Konstruktor IDBVersionChangeEvent() erzeugt ein Event-Objekt, das eine Versionsänderung einer IndexedDB-Datenbank beschreibt. Normalerweise erzeugt der Browser solche Events selbst: bei upgradeneeded (eine Datenbank wird mit höherer Version geöffnet), bei versionchange (eine andere Verbindung will die Version ändern oder die Datenbank löschen), bei blocked und beim success von indexedDB.deleteDatabase().
Selbst aufrufen muss man den Konstruktor vor allem in Unit-Tests, Mocks und Polyfills (z. B. fake-indexeddb). Dort will man Upgrade-Logik oder Handler für versionchange prüfen, ohne eine echte Datenbank anzulegen. Die Eigenschaften oldVersion und newVersion legt man über das Options-Objekt fest.
Das Event erbt von Event. newVersion ist null, wenn die Datenbank gelöscht wird. Ein selbst erzeugtes Event hat isTrusted === false und löst im Browser kein echtes Schema-Upgrade aus. Innerhalb eines von Hand ausgelösten Handlers gibt es also auch keine Versionsänderungs-Transaktion.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Name des Events, typischerweise "upgradeneeded", "versionchange", "blocked" oder "success". |
|
| $options | object | {} | Optionales Wörterbuch (IDBVersionChangeEventInit). Es erweitert EventInit um:
|
Rückgabewert
IDBVersionChangeEvent-Objekt mit den angegebenen Werten für oldVersion und newVersion.Beispiele
Event erzeugen und Eigenschaften lesen
const event = new IDBVersionChangeEvent('upgradeneeded', {
oldVersion: 1,
newVersion: 2
});
console.log(event.type); // Event-Name
console.log(event.oldVersion); // alte Version
console.log(event.newVersion); // neue Version
console.log(event.isTrusted); // selbst erzeugt => falseUpgrade-Logik im Unit-Test prüfen
// Migrationslogik, unabhängig von einer echten Datenbank
const getMigrations = (event) => {
const steps = [];
if (event.oldVersion < 1) steps.push('Store "users" anlegen');
if (event.oldVersion < 2) steps.push('Index "email" anlegen');
if (event.oldVersion < 3) steps.push('Store "settings" anlegen');
return steps;
};
const fakeEvent = new IDBVersionChangeEvent('upgradeneeded', {
oldVersion: 1,
newVersion: 3
});
console.log(getMigrations(fakeEvent));versionchange-Handler per dispatchEvent testen
// EventTarget ersetzt hier die IDBDatabase-Verbindung
const fakeDb = new EventTarget();
let closed = false;
fakeDb.addEventListener('versionchange', (event) => {
if (event.newVersion === null) {
console.log('Datenbank wird gelöscht – Verbindung schließen');
} else {
console.log(`Update auf Version ${event.newVersion} – bitte neu laden`);
}
closed = true;
});
fakeDb.dispatchEvent(
new IDBVersionChangeEvent('versionchange', { oldVersion: 2, newVersion: null })
);
console.log('closed:', closed);// Wichtig · Fallstricke
- Kein echtes Upgrade: Ein selbst erzeugtes und ausgelöstes Event startet keine Versionsänderungs-Transaktion.
createObjectStore()funktioniert nur in einem echtenupgradeneeded-Handler vonindexedDB.open(). newVersionist standardmäßignull. Vergisst man den Wert, sieht es für den Handler so aus, als würde die Datenbank gelöscht.- Ohne den Aufruf mit
newwirft der Konstruktor einenTypeError. Fehlt das Argumenttype, gibt es ebenfalls einenTypeError. - Die frühere, nicht standardisierte Eigenschaft
versionund die MethodeinitIDBVersionChangeEvent()gelten als veraltet und sind entfernt. Verwende nuroldVersionundnewVersion. - Browser-Kompatibilität: In allen aktuellen Browsern verfügbar, auch in Web Workern. In Node.js gibt es IndexedDB nicht eingebaut; dort hilft z. B.
fake-indexeddb. - Praxis-Tipp: Im echten
versionchange-Handler immerdb.close()aufrufen. Sonst bleiben Upgrades in anderen Tabs mitblockedhängen.