IDBVersionChangeEvent.newVersion — Eigenschaft · JavaScript-Referenz

Signatur

IDBVersionChangeEvent.newVersion

Beschreibung

Die Eigenschaft newVersion des Interfaces IDBVersionChangeEvent gibt an, auf welche Versionsnummer eine IndexedDB-Datenbank gerade aktualisiert wird. Sie steht in den Ereignissen upgradeneeded (an der IDBOpenDBRequest), versionchange (an einer bereits offenen IDBDatabase) und blocked zur Verfügung.

Zusammen mit oldVersion ist sie die Grundlage für schrittweise Schema-Migrationen: Im upgradeneeded-Handler vergleicht man alte und neue Version und legt nur die Object Stores und Indizes an, die in den dazwischenliegenden Versionen hinzugekommen sind.

Wird die Datenbank mit indexedDB.deleteDatabase() gelöscht, ist newVersion null. Das ist vor allem im versionchange-Handler anderer Tabs wichtig: Dort lässt sich unterscheiden, ob ein Upgrade oder eine Löschung ansteht – in beiden Fällen sollte die eigene Verbindung mit db.close() geschlossen werden, damit der Vorgang nicht blockiert.

Rückgabewert

Typ

number | null

Beschreibung

Die neue Versionsnummer als positive Ganzzahl (64-Bit, unsigned long long) oder null, wenn die Datenbank gelöscht wird.

Beispiele

Schrittweise Migration im upgradeneeded-Handler

const request = indexedDB.open('shop', 3);

request.addEventListener('upgradeneeded', (event) => {
  const db = request.result;
  const { oldVersion, newVersion } = event;
  console.log(`Upgrade von v${oldVersion} auf v${newVersion}`);

  // Bewusst ohne break: jede Stufe baut auf der vorherigen auf
  if (oldVersion < 1) {
    db.createObjectStore('produkte', { keyPath: 'id' });
  }
  if (oldVersion < 2) {
    const store = request.transaction.objectStore('produkte');
    store.createIndex('nachKategorie', 'kategorie');
  }
  if (oldVersion < 3) {
    db.createObjectStore('warenkorb', { autoIncrement: true });
  }
});

request.addEventListener('success', () => {
  console.log('Datenbank bereit, Version:', request.result.version);
});

Upgrade von v0 auf v3 Datenbank bereit, Version: 3

Andere Tabs auf Upgrade oder Löschung reagieren lassen

const request = indexedDB.open('shop', 3);

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

  db.onversionchange = (event) => {
    db.close(); // Verbindung freigeben, sonst wird der andere Tab blockiert
    if (event.newVersion === null) {
      console.warn('Datenbank wird gelöscht.');
    } else {
      console.warn(`Neue Version ${event.newVersion} verfügbar – bitte Seite neu laden.`);
    }
  };
};

Neue Version 4 verfügbar – bitte Seite neu laden.

newVersion beim Löschen der Datenbank

const del = indexedDB.deleteDatabase('shop');

del.onblocked = (event) => {
  console.log('Blockiert, newVersion =', event.newVersion);
};

del.onsuccess = (event) => {
  console.log('Gelöscht. oldVersion:', event.oldVersion, 'newVersion:', event.newVersion);
};

Gelöscht. oldVersion: 3 newVersion: null

// Wichtig · Fallstricke

null prüfen: Beim Löschen ist newVersion null. Vergleiche wie event.newVersion > 2 liefern dann false, ohne einen Fehler auszulösen – explizit auf null testen.
Die Eigenschaft ist schreibgeschützt. Die Zielversion legt man ausschließlich über den zweiten Parameter von indexedDB.open(name, version) fest; Versionsnummern müssen ganzzahlig und größer als 0 sein, eine Herabstufung führt zu einem VersionError.
Ruft man open() ohne Version für eine neue Datenbank auf, wird Version 1 angelegt und newVersion ist 1.
Ältere Browser (vor IndexedDB 2.0, z. B. alte WebKit-Versionen) lieferten teilweise abweichende Werte; in allen aktuellen Browsern ist das Verhalten einheitlich. Im privaten Modus einiger Browser ist IndexedDB eingeschränkt.
Ohne db.close() im versionchange-Handler bleibt das Upgrade in anderen Tabs im blocked-Zustand hängen.

Siehe auch

IDBVersionChangeEvent IDBVersionChangeEvent.oldVersion IDBFactory.open() IDBFactory.deleteDatabase() BufferedChangeEvent.removedRanges