IDBDatabase: versionchange — Ereignis · JavaScript-Referenz

Signatur

IDBDatabase.addEventListener("versionchange", handler)

Beschreibung

Das Ereignis versionchange vom Typ IDBVersionChangeEvent wird an eine bereits geöffnete Datenbankverbindung gesendet, wenn ein anderer Kontext (anderer Tab, Worker, iframe oder derselbe Tab mit einer zweiten Verbindung) die Datenbank mit einer höheren Version öffnen will (indexedDB.open(name, neueVersion)) oder sie mit indexedDB.deleteDatabase(name) löschen möchte.

Ein Upgrade oder Löschen kann erst ausgeführt werden, wenn alle anderen Verbindungen geschlossen sind. Deshalb solltest du in diesem Handler fast immer db.close() aufrufen und den Nutzer ggf. bitten, die Seite neu zu laden. Tust du das nicht, erhält die anfordernde Seite ein blocked-Ereignis auf ihrem IDBOpenDBRequest und wartet, bis deine Verbindung geschlossen wird.

Registrieren lässt sich der Handler per db.addEventListener("versionchange", handler) oder über die Eigenschaft db.onversionchange = handler. Das Ereignisobjekt liefert oldVersion (aktuelle Version) und newVersion (angeforderte Version bzw. null beim Löschen).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"versionchange"`.
$handler Pflicht	(event: IDBVersionChangeEvent) => void		Callback, der ein `IDBVersionChangeEvent` mit `oldVersion` und `newVersion` erhält.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Ereignis ist nicht abbrechbar und blubbert nicht.

Beispiele

Verbindung bei Upgrade in anderem Tab schließen

const request = indexedDB.open('notizen', 1);

request.onupgradeneeded = () => {
  request.result.createObjectStore('eintraege', { keyPath: 'id' });
};

request.onsuccess = () => {
  const db = request.result;

  db.addEventListener('versionchange', (event) => {
    console.log(`Version ${event.oldVersion} → ${event.newVersion}`);
    db.close(); // Upgrade im anderen Tab nicht blockieren
    alert('Eine neue Version der App ist verfügbar. Bitte Seite neu laden.');
  });
};

Version 1 → 2

on-Property nutzen und Löschen erkennen

const openDb = (name, version) => new Promise((resolve, reject) => {
  const req = indexedDB.open(name, version);
  req.onsuccess = () => resolve(req.result);
  req.onerror = () => reject(req.error);
});

const db = await openDb('cache', 1);

db.onversionchange = (event) => {
  if (event.newVersion === null) {
    console.log('Datenbank wird gelöscht – Verbindung wird geschlossen');
  }
  db.close();
};

// Löschen aus demselben Kontext löst versionchange auf db aus
const del = indexedDB.deleteDatabase('cache');
del.onsuccess = () => console.log('Gelöscht');

Datenbank wird gelöscht – Verbindung wird geschlossen Gelöscht

Gegenseite: blocked-Ereignis behandeln

const req = indexedDB.open('notizen', 2);

req.onblocked = () => {
  // Eine andere Verbindung hat versionchange ignoriert
  console.warn('Upgrade blockiert – bitte andere Tabs schließen.');
};

req.onupgradeneeded = (event) => {
  const db = req.result;
  if (event.oldVersion < 2) {
    db.createObjectStore('tags', { autoIncrement: true });
  }
};

req.onsuccess = () => console.log('Upgrade auf Version', req.result.version);

Upgrade auf Version 2

// Wichtig · Fallstricke

Immer db.close() aufrufen: Ohne Schließen bleibt das Upgrade bzw. Löschen in anderen Tabs hängen (blocked), bis dieser Tab geschlossen wird.
Nach close() sind keine neuen Transaktionen mehr möglich; laufende Transaktionen werden noch abgeschlossen. Plane einen Neustart/Reload der App-Logik ein.
Beim Löschen via deleteDatabase() ist event.newVersion null.
Nicht verwechseln mit upgradeneeded (auf IDBOpenDBRequest) und dem veralteten versionchange-Ereignis auf Requests aus alten Spezifikationsentwürfen.
Kompatibilität: in allen modernen Browsern unterstützt (auch in Web Workern); in privaten Modi mancher Browser ist IndexedDB eingeschränkt.

Siehe auch

IDBDatabase IDBVersionChangeEvent IDBOpenDBRequest: upgradeneeded IDBOpenDBRequest: blocked IDBDatabase.prototype.close() IDBFactory.prototype.deleteDatabase() HTMLInputElement: selectionchange