IDBFactory.open() — Methode · JavaScript-Referenz

Signatur

IDBFactory.prototype.open(name, version)

Beschreibung

Mit indexedDB.open() öffnen Sie eine Verbindung zu einer IndexedDB-Datenbank. Ruft man die Methode auf, bekommt man nicht direkt die Datenbank zurück, sondern ein IDBOpenDBRequest. Das Ergebnis kommt später über Ereignisse an: Bei success steht in request.result ein IDBDatabase-Objekt, bei error steht der Fehler in request.error.

Gibt es die Datenbank noch nicht, wird sie angelegt. Dasselbe passiert, wenn die angegebene version höher ist als die gespeicherte: Dann wird zuerst das Ereignis upgradeneeded ausgelöst. Nur in diesem Handler dürfen Sie Objektspeicher (createObjectStore()) und Indizes (createIndex()) anlegen oder löschen. Der Handler läuft innerhalb einer automatisch erzeugten versionchange-Transaktion.

Halten andere Tabs oder Fenster noch eine Verbindung mit einer älteren Version offen, bekommen diese ein versionchange-Ereignis. Schließen sie ihre Verbindung nicht, erhält die neue Anfrage ein blocked-Ereignis und wartet, bis die alten Verbindungen geschlossen sind.

Die API arbeitet mit Ereignissen. Deshalb lohnt es sich meist, open() in ein Promise zu verpacken, um mit async/await zu arbeiten. Alternativ können Sie eine schlanke Bibliothek wie idb nutzen.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name der Datenbank. Innerhalb eines Ursprungs (Origin) eindeutig; Groß- und Kleinschreibung wird unterschieden.
$version	number	Aktuelle Version bzw. 1 bei neuer Datenbank	Positive ganze Zahl (`unsigned long long`) für die Schema-Version. Ist sie höher als die gespeicherte Version, wird `upgradeneeded` ausgelöst. `0`, negative Werte oder Werte, die keine Zahl sind, führen zu einem `TypeError`.

Rückgabewert

Typ

IDBOpenDBRequest

Beschreibung

Ein Anfrageobjekt, das die Ereignisse success, error, upgradeneeded und blocked auslöst. Nach dem Erfolg enthält result die geöffnete IDBDatabase.

Beispiele

Datenbank öffnen und Schema anlegen

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

request.addEventListener('upgradeneeded', (event) => {
  const db = request.result;
  console.log(`Upgrade von ${event.oldVersion} auf ${event.newVersion}`);
  // Objektspeicher und Index nur hier anlegen
  const store = db.createObjectStore('produkte', { keyPath: 'id', autoIncrement: true });
  store.createIndex('nachName', 'name', { unique: false });
});

request.addEventListener('success', () => {
  const db = request.result;
  console.log('Geöffnet:', db.name, 'Version', db.version);
});

request.addEventListener('error', () => {
  console.error('Fehler beim Öffnen:', request.error);
});

Upgrade von 0 auf 1 Geöffnet: shop Version 1

Promise-Wrapper für async/await

const openDB = (name, version, onUpgrade) =>
  new Promise((resolve, reject) => {
    const req = indexedDB.open(name, version);
    req.onupgradeneeded = (e) => onUpgrade?.(req.result, e.oldVersion, req.transaction);
    req.onsuccess = () => resolve(req.result);
    req.onerror = () => reject(req.error);
    req.onblocked = () => console.warn('Öffnen blockiert – bitte andere Tabs schließen.');
  });

const db = await openDB('notizen', 1, (db) => {
  db.createObjectStore('eintraege', { keyPath: 'id' });
});

const tx = db.transaction('eintraege', 'readwrite');
tx.objectStore('eintraege').put({ id: 1, text: 'Hallo IndexedDB' });
tx.oncomplete = () => console.log('Gespeichert');

Gespeichert

Schrittweise Schema-Migration und versionchange behandeln

const req = indexedDB.open('app', 3);

req.onupgradeneeded = (event) => {
  const db = req.result;
  const tx = req.transaction; // versionchange-Transaktion
  // Migrationen schrittweise nachziehen
  if (event.oldVersion < 1) {
    db.createObjectStore('nutzer', { keyPath: 'id' });
  }
  if (event.oldVersion < 2) {
    tx.objectStore('nutzer').createIndex('email', 'email', { unique: true });
  }
  if (event.oldVersion < 3) {
    db.createObjectStore('einstellungen');
  }
};

req.onsuccess = () => {
  const db = req.result;
  // Verbindung freigeben, wenn ein anderer Tab eine neuere Version öffnet
  db.onversionchange = () => {
    db.close();
    console.log('Neue Version verfügbar – bitte Seite neu laden.');
  };
  console.log([...db.objectStoreNames]);
};

["einstellungen", "nutzer"]

// Wichtig · Fallstricke

Keine niedrigere Version: Ist version kleiner als die gespeicherte Version, schlägt die Anfrage mit einem VersionError fehl.
Schemaänderungen nur in upgradeneeded: Rufen Sie createObjectStore() außerhalb dieses Handlers auf, wird ein InvalidStateError geworfen. Das Schema lässt sich also nur ändern, indem Sie die Versionsnummer erhöhen.
Blockierung: Registrieren Sie in jeder Verbindung einen onversionchange-Handler, der db.close() aufruft. Sonst bleiben Upgrades in anderen Tabs im Zustand blocked hängen.
Ganzzahlen verwenden: open('db', 2.5) wird zu 2 abgerundet. Das kann zu unerwartetem Verhalten führen.
Kontext und Datenschutz: IndexedDB ist an den Ursprung (Same-Origin) gebunden. In privaten Fenstern ist sie je nach Browser eingeschränkt oder wird beim Schließen gelöscht. In Firefox war sie im privaten Modus früher ganz gesperrt (Fehler InvalidStateError). Auf file://-URLs und in Iframes, die Speicher von Drittanbietern blockieren, kann der Aufruf mit einem SecurityError scheitern.
Kompatibilität: Wird in allen modernen Browsern und in Web Workern unterstützt. Der frühere dritte Parameter { storage: 'persistent' } war nur in Firefox verfügbar und ist veraltet. Für dauerhaften Speicher nutzen Sie stattdessen navigator.storage.persist().

Siehe auch

IDBFactory IDBFactory.deleteDatabase() IDBFactory.databases() IDBOpenDBRequest IDBDatabase IDBDatabase.createObjectStore() IDBDatabase.transaction()