IDBDatabase.version — Eigenschaft · JavaScript-Referenz

Signatur

IDBDatabase.version

Beschreibung

Die Eigenschaft version eines IDBDatabase-Objekts enthält die Versionsnummer der Datenbank, mit der die Verbindung besteht. Sie ist schreibgeschützt. Ändern lässt sich die Version nur, wenn man die Datenbank mit indexedDB.open(name, neueVersion) und einer höheren Versionsnummer neu öffnet.

Das Versionsschema von IndexedDB ist die Grundlage für Schema-Migrationen. Ist die angeforderte Version höher als die gespeicherte, feuert das Ereignis upgradeneeded. Nur innerhalb dieser versionchange-Transaktion dürfen Object Stores und Indizes angelegt oder gelöscht werden. Während des Upgrades liefert db.version bereits die neue Version. Die alte Version findet man in event.oldVersion.

Typische Einsatzzwecke sind das Protokollieren der Schema-Version, Diagnose und Fehlersuche sowie Code, der sich je nach Datenbankversion unterschiedlich verhalten soll. Eine neu angelegte Datenbank ohne Angabe einer Version bekommt die Version 1.

Rückgabewert

Typ

number

Beschreibung

Eine positive Ganzzahl mit der aktuellen Version der verbundenen Datenbank. Laut Spezifikation ist das ein unsigned long long, in JavaScript wird es als number geliefert.

Beispiele

Version nach dem Öffnen auslesen

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

request.onsuccess = (event) => {
  const db = event.target.result;
  console.log(`Datenbank "${db.name}" hat Version ${db.version}`);
  db.close();
};

request.onerror = () => console.error('Öffnen fehlgeschlagen:', request.error);

Datenbank "notizen" hat Version 1

Schema-Migration mit oldVersion und version

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

request.onupgradeneeded = (event) => {
  const db = event.target.result;
  console.log(`Upgrade von ${event.oldVersion} auf ${db.version}`);

  // Migrationen der Reihe nach anwenden
  if (event.oldVersion < 1) {
    db.createObjectStore('produkte', { keyPath: 'id' });
  }
  if (event.oldVersion < 2) {
    const store = request.transaction.objectStore('produkte');
    store.createIndex('nachName', 'name');
  }
  if (event.oldVersion < 3) {
    db.createObjectStore('warenkorb', { autoIncrement: true });
  }
};

request.onsuccess = () => {
  console.log('Aktuelle Version:', request.result.version);
};

Upgrade von 0 auf 3 Aktuelle Version: 3

Promise-Helfer: aktuelle Version ermitteln

const getDbVersion = (name) =>
  new Promise((resolve, reject) => {
    // Ohne Versionsangabe wird die bestehende Version geöffnet
    const req = indexedDB.open(name);
    req.onsuccess = () => {
      const { version } = req.result;
      req.result.close();
      resolve(version);
    };
    req.onerror = () => reject(req.error);
  });

const version = await getDbVersion('shop');
console.log(`Schema-Version: ${version}`);

Schema-Version: 3

// Wichtig · Fallstricke

Schreibgeschützt: db.version = 5 hat keine Wirkung (im strikten Modus gibt es einen TypeError). Um die Version zu erhöhen, öffnet man die Datenbank mit indexedDB.open(name, höhereVersion) neu.
Keine Rückstufung: Wird eine niedrigere Version als die gespeicherte angefordert, schlägt open() mit einem VersionError fehl.
Nur Ganzzahlen: Versionen wie 1.5 werden zu 1 abgerundet. 0 und negative Werte führen zu einem TypeError.
Offene Verbindungen blockieren Upgrades: Solange andere Tabs die alte Version geöffnet halten, feuert blocked. In diesen Tabs sollte man im Handler onversionchange die Methode db.close() aufrufen.
Ältere Implementierungen (vor IndexedDB 2.0) kannten die Methode setVersion() und Versionen als Strings. Beides ist veraltet.
Die Eigenschaft wird in allen modernen Browsern unterstützt, auch in Web Workern. In Node.js gibt es IndexedDB nicht nativ (Polyfill z. B. fake-indexeddb).

Siehe auch

IDBDatabase IDBDatabase.name IDBFactory.prototype.open() IDBVersionChangeEvent.oldVersion CSSMathValue.operator