IDBFactory — Schnittstelle · JavaScript-Referenz

Signatur

interface IDBFactory

Beschreibung

IDBFactory ist der Einstiegspunkt in die IndexedDB-API. Eine eigene Instanz legt man nie an: Der Browser stellt sie als globale Eigenschaft indexedDB bereit, sowohl im Fenster (window.indexedDB) als auch in Web Workern und Service Workern (self.indexedDB).

Die wichtigsten Methoden sind:

open(name, version): öffnet eine Datenbank oder legt sie an und gibt einen IDBOpenDBRequest zurück.
deleteDatabase(name): löscht eine Datenbank vollständig.
databases(): liefert ein Promise mit der Liste aller Datenbanken dieses Ursprungs (Origin), jeweils mit Name und Version.
cmp(a, b): vergleicht zwei Schlüssel nach den Sortierregeln von IndexedDB und gibt -1, 0 oder 1 zurück.

Außer databases() und cmp() arbeiten die Methoden ereignisbasiert mit Request-Objekten und nicht mit Promises. Das Ergebnis erhält man über die Ereignisse success, error, upgradeneeded und blocked. Das Datenbankschema, also Object Stores und Indizes, lässt sich nur im Handler von upgradeneeded ändern. Dieses Ereignis wird ausgelöst, wenn die angeforderte Version höher ist als die gespeicherte.

In der Praxis verpackt man open() oft in ein Promise oder nutzt eine kleine Bibliothek wie idb. So lässt sich der Code mit async/await schreiben.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name der Datenbank für `open()` und `deleteDatabase()`.
$version	number	1 bzw. die bestehende Version	Nur bei `open()`: eine positive ganze Zahl (`unsigned long long`). Ist sie höher als die gespeicherte Version, wird `upgradeneeded` ausgelöst. Ist sie niedriger, schlägt der Aufruf mit `VersionError` fehl.
$first, second Pflicht	any (gültiger IDB-Schlüssel)		Nur bei `cmp()`: die beiden zu vergleichenden Schlüssel. Erlaubt sind Zahl, Datum, String, Binärdaten oder Array. Ungültige Schlüssel lösen einen `DataError` aus.

Rückgabewert

Typ

IDBOpenDBRequest | Promise<Array<{name: string, version: number}>> | number

Beschreibung

open() und deleteDatabase() geben einen IDBOpenDBRequest zurück, databases() ein Promise mit Datenbank-Infos und cmp() die Zahl -1, 0 oder 1.

Beispiele

Datenbank öffnen und Schema anlegen (als Promise verpackt)

const openDB = (name, version) => new Promise((resolve, reject) => {
  const request = indexedDB.open(name, version);

  request.onupgradeneeded = (event) => {
    const db = request.result;
    // Schema nur hier änderbar
    if (!db.objectStoreNames.contains('notizen')) {
      const store = db.createObjectStore('notizen', { keyPath: 'id', autoIncrement: true });
      store.createIndex('nachDatum', 'erstellt');
    }
    console.log(`Upgrade von ${event.oldVersion} auf ${event.newVersion}`);
  };

  request.onsuccess = () => resolve(request.result);
  request.onerror = () => reject(request.error);
  request.onblocked = () => console.warn('Andere Tabs halten noch eine alte Version offen.');
});

const db = await openDB('meine-app', 1);
console.log(db.name, db.version);

Upgrade von 0 auf 1 meine-app 1

Datensatz speichern nach dem Öffnen

const request = indexedDB.open('meine-app', 1);

request.onsuccess = () => {
  const db = request.result;
  const tx = db.transaction('notizen', 'readwrite');
  tx.objectStore('notizen').add({ text: 'Einkaufen', erstellt: new Date() });
  tx.oncomplete = () => {
    console.log('Gespeichert');
    db.close();
  };
};

Gespeichert

Alle Datenbanken auflisten und eine löschen

const dbs = await indexedDB.databases();
console.log(dbs); // z. B. [{ name: 'meine-app', version: 1 }]

const del = indexedDB.deleteDatabase('meine-app');
del.onsuccess = () => console.log('Datenbank gelöscht');
del.onerror = () => console.error(del.error);
del.onblocked = () => console.warn('Löschen blockiert – Verbindungen noch offen');

[{ name: 'meine-app', version: 1 }] Datenbank gelöscht

Schlüssel mit cmp() vergleichen

console.log(indexedDB.cmp(1, 2));        // Zahl < Zahl
console.log(indexedDB.cmp('b', 'a'));    // String-Vergleich
console.log(indexedDB.cmp(100, 'a'));    // Zahlen stehen vor Strings
console.log(indexedDB.cmp([1, 2], [1, 2]));

-1 1 -1 0

// Wichtig · Fallstricke

Ereignis blocked: Ein Versions-Upgrade oder deleteDatabase() wartet, bis alle anderen offenen Verbindungen geschlossen sind, etwa in anderen Tabs. Reagieren Sie deshalb in bestehenden Verbindungen auf db.onversionchange und rufen Sie dort db.close() auf.
Versionsnummer: Sie muss eine ganze Zahl ≥ 1 sein. 0 oder negative Werte lösen einen TypeError aus. Kommazahlen werden abgeschnitten, aus 1.5 wird also 1.
Kompatibilität: open(), deleteDatabase() und cmp() funktionieren in allen modernen Browsern. databases() fehlte lange in Firefox und wird erst ab Firefox 126 unterstützt; prüfen Sie die Methode vorher mit 'databases' in indexedDB.
Privater Modus und Speicherlimits: Im privaten Modus kann IndexedDB eingeschränkt sein oder beim Schließen gelöscht werden. Der Speicher unterliegt außerdem Kontingenten (Quotas); bei Überschreitung tritt ein QuotaExceededError auf.
Sicherheit: Die Daten sind an den Ursprung (Origin) gebunden, also an Protokoll, Host und Port, und sind nicht verschlüsselt. Speichern Sie dort keine sensiblen Geheimnisse wie Tokens im Klartext, denn jedes Skript auf derselben Origin kann sie lesen, auch eingeschleustes XSS.
In Sandbox-iframes ohne allow-same-origin oder bei blockierten Drittanbieter-Cookies kann schon der Zugriff auf indexedDB einen SecurityError auslösen.

Siehe auch

IDBRecord IDBCursor History NDEFRecord Attr