Signatur
Beschreibung
IDBVersionChangeEvent ist das Ereignis-Objekt, das die IndexedDB API immer dann nutzt, wenn sich die Version einer Datenbank ändert oder ändern soll. Es wird bei den Ereignissen upgradeneeded (auf dem IDBOpenDBRequest), blocked (auf dem IDBOpenDBRequest) und versionchange (auf einer bereits geöffneten IDBDatabase) ausgelöst. Beim Löschen einer Datenbank über indexedDB.deleteDatabase() erhält auch das success-Ereignis ein IDBVersionChangeEvent.
Die wichtigsten Eigenschaften sind oldVersion (bisherige Version, 0 bei einer neu angelegten Datenbank) und newVersion (Zielversion bzw. null, wenn die Datenbank gelöscht wird). Damit lassen sich inkrementelle Schema-Migrationen umsetzen: Je nach oldVersion werden nur die fehlenden Object Stores und Indizes angelegt.
Nur im upgradeneeded-Handler läuft eine versionchange-Transaktion, in der createObjectStore(), deleteObjectStore() und createIndex() erlaubt sind. Das Ereignis versionchange auf einer offenen Verbindung ist das Signal, diese Verbindung mit db.close() zu schließen, damit ein Upgrade in einem anderen Tab nicht blockiert wird.
Der Konstruktor new IDBVersionChangeEvent(type, options) existiert zwar, wird aber praktisch nur für Tests gebraucht. In normalem Code bekommt man das Objekt vom Browser.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Nur für den Konstruktor: Name des Ereignisses, z. B. "upgradeneeded", "versionchange" oder "blocked". |
|
| $options | { oldVersion?: number, newVersion?: number | null, bubbles?: boolean, cancelable?: boolean } | { oldVersion: 0, newVersion: null } | Nur für den Konstruktor: Anfangswerte für oldVersion und newVersion sowie die üblichen Event-Optionen. |
Rückgabewert
oldVersion (number) und newVersion (number | null).Beispiele
Schema-Migration im upgradeneeded-Handler
const request = indexedDB.open('shop', 3);
request.addEventListener('upgradeneeded', (event) => {
const db = request.result;
console.log(`Upgrade von v${event.oldVersion} auf v${event.newVersion}`);
// Migrationen schrittweise nachholen (bewusst ohne break)
switch (event.oldVersion) {
case 0:
db.createObjectStore('products', { keyPath: 'id' });
case 1: {
const store = request.transaction.objectStore('products');
store.createIndex('by_name', 'name');
}
case 2:
db.createObjectStore('orders', { autoIncrement: true });
}
});
request.addEventListener('success', () => {
console.log('Datenbank bereit:', request.result.version);
});Offene Verbindung bei versionchange schließen
const openDb = () => new Promise((resolve, reject) => {
const req = indexedDB.open('shop', 3);
req.onsuccess = () => {
const db = req.result;
// Ein anderer Tab möchte upgraden oder löschen
db.onversionchange = (event) => {
console.log(`Anderer Tab will v${event.newVersion} – Verbindung wird geschlossen`);
db.close();
};
resolve(db);
};
req.onerror = () => reject(req.error);
});
const db = await openDb();Blockiertes Upgrade erkennen
const req = indexedDB.open('shop', 4);
req.onblocked = (event) => {
console.warn(
`Upgrade v${event.oldVersion} → v${event.newVersion} blockiert. Bitte andere Tabs schließen.`
);
};
req.onupgradeneeded = (event) => {
console.log('Upgrade läuft, alte Version:', event.oldVersion);
};Ereignis für Tests selbst erzeugen
const evt = new IDBVersionChangeEvent('versionchange', {
oldVersion: 2,
newVersion: 3
});
console.log(evt instanceof Event, evt.type, evt.oldVersion, evt.newVersion);// Wichtig · Fallstricke
- Kein
breakim Migrations-switch: Das bewusste Durchfallen sorgt dafür, dass Nutzer mit sehr alter Version alle Zwischenschritte durchlaufen. newVersionistnull, wenn die Datenbank überdeleteDatabase()gelöscht wird. Wer imversionchange-Handler damit rechnet, muss diesen Fall abfangen.- Blockierung: Schließen offene Verbindungen in anderen Tabs nicht per
db.close(), bleibt das Upgrade hängen (blocked). Deshalb immer einenonversionchange-Handler registrieren. - Schemaänderungen (
createObjectStore,createIndex) sind nur während der Versionswechsel-Transaktion imupgradeneeded-Handler erlaubt, sonst wird eineInvalidStateError-DOMExceptiongeworfen. - Die Version muss eine positive ganze Zahl sein. Eine niedrigere Version als die bestehende führt zu einem
VersionError. - Die frühere, nicht standardisierte Eigenschaft
dataLosssowie die veraltete MethodeIDBDatabase.setVersion()sollten nicht mehr verwendet werden. - Kompatibilität: in allen modernen Browsern verfügbar, auch in Web Workern. In privaten Fenstern mancher Browser ist IndexedDB eingeschränkt oder nur flüchtig.