IDBDatabase — Schnittstelle · JavaScript-Referenz

Signatur

interface IDBDatabase extends EventTarget

Beschreibung

IDBDatabase steht für eine offene Verbindung zu einer IndexedDB-Datenbank. Sie erzeugen das Objekt nicht selbst: Es steht in request.result, nachdem indexedDB.open() erfolgreich war (im Event success oder upgradeneeded). Über diese Verbindung starten Sie mit transaction() Transaktionen, um Daten in Object Stores zu lesen und zu schreiben.

Die Struktur der Datenbank lässt sich nur im Event upgradeneeded ändern, also in einer versionchange-Transaktion. Nur dort dürfen Sie createObjectStore() und deleteObjectStore() aufrufen. Das Event wird ausgelöst, wenn Sie beim Öffnen eine höhere Versionsnummer angeben als die gespeicherte.

Wichtige Mitglieder:

Eigenschaften: name (Name der Datenbank), version (aktuelle Versionsnummer, 64-Bit-Ganzzahl), objectStoreNames (DOMStringList mit allen Store-Namen).
Methoden: transaction(storeNames, mode, options), createObjectStore(name, options), deleteObjectStore(name), close().
Events: versionchange (ein anderer Tab will die Version erhöhen), close (die Verbindung wurde unerwartet geschlossen), abort und error (von Transaktionen hochgereicht).

Behandeln Sie in der Praxis immer versionchange und schließen Sie die Verbindung dort mit close(). Sonst blockiert eine alte Verbindung in einem anderen Tab das Upgrade: Die neue Anfrage bekommt ein blocked-Event und wartet unbegrenzt.

Parameter

Name	Typ	Default	Beschreibung
$storeNames Pflicht	string \| string[]		Für `transaction()`: Name oder Liste der Object Stores, die die Transaktion umfasst.
$mode	"readonly" \| "readwrite"	"readonly"	Für `transaction()`: Zugriffsmodus. Nur `readwrite` erlaubt Schreibzugriffe.
$options	{ durability?: "default" \| "strict" \| "relaxed" }	{ durability: "default" }	Für `transaction()`: Hinweis zur Dauerhaftigkeit. `relaxed` ist schneller, bietet aber weniger Absturzsicherheit.
$name Pflicht	string		Für `createObjectStore()` und `deleteObjectStore()`: Name des Object Stores.
$storeOptions	{ keyPath?: string \| string[], autoIncrement?: boolean }	{}	Für `createObjectStore()`: Schlüsselpfad und/oder automatisch hochgezählte Schlüssel.

Rückgabewert

Typ

IDBDatabase

Beschreibung

Liegt in IDBOpenDBRequest.result vor. transaction() gibt eine IDBTransaction zurück, createObjectStore() einen IDBObjectStore, close() und deleteObjectStore() geben undefined zurück.

Beispiele

Datenbank öffnen und Schema anlegen

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

  request.onupgradeneeded = (event) => {
    const db = event.target.result; // IDBDatabase
    if (!db.objectStoreNames.contains('kunden')) {
      const store = db.createObjectStore('kunden', { keyPath: 'id', autoIncrement: true });
      store.createIndex('email', 'email', { unique: true });
    }
  };

  request.onsuccess = () => resolve(request.result);
  request.onerror = () => reject(request.error);
  request.onblocked = () => console.warn('Upgrade blockiert – bitte andere Tabs schließen');
});

const db = await openDB('shop', 1);
console.log(db.name, db.version, [...db.objectStoreNames]);

shop 1 ["kunden"]

Daten in einer readwrite-Transaktion schreiben und lesen

const kundeSpeichern = (db, kunde) => new Promise((resolve, reject) => {
  const tx = db.transaction('kunden', 'readwrite');
  const req = tx.objectStore('kunden').add(kunde);
  let id;
  req.onsuccess = () => { id = req.result; };
  tx.oncomplete = () => resolve(id); // erst jetzt sind die Daten sicher gespeichert
  tx.onerror = () => reject(tx.error);
});

const kundeLaden = (db, id) => new Promise((resolve, reject) => {
  const req = db.transaction('kunden').objectStore('kunden').get(id);
  req.onsuccess = () => resolve(req.result);
  req.onerror = () => reject(req.error);
});

const id = await kundeSpeichern(db, { name: 'Anna', email: 'anna@example.de' });
console.log(await kundeLaden(db, id));

{ name: 'Anna', email: 'anna@example.de', id: 1 }

Auf versionchange reagieren und Verbindung schließen

db.addEventListener('versionchange', () => {
  // Ein anderer Tab öffnet eine neuere Version – Platz machen
  db.close();
  alert('Eine neue Version der App ist verfügbar. Bitte Seite neu laden.');
});

db.onclose = () => {
  console.warn('Verbindung wurde vom Browser geschlossen (z. B. Speicher gelöscht).');
};

Object Store bei einem Versions-Upgrade entfernen

const req = indexedDB.open('shop', 2);
req.onupgradeneeded = (event) => {
  const db = req.result;
  console.log(`Upgrade von ${event.oldVersion} auf ${event.newVersion}`);
  if (db.objectStoreNames.contains('altlasten')) {
    db.deleteObjectStore('altlasten');
  }
};
req.onsuccess = () => req.result.close();

Upgrade von 1 auf 2

// Wichtig · Fallstricke

Schema nur im Upgrade ändern: Wenn Sie createObjectStore() oder deleteObjectStore() außerhalb von upgradeneeded aufrufen, wird ein InvalidStateError geworfen.
Transaktionen schließen sich automatisch: Eine Transaktion wird beendet, sobald keine Anfragen mehr offen sind. Wenn Sie zwischendurch auf ein fremdes await warten, zum Beispiel auf fetch, ist die Transaktion danach inaktiv und es kommt zum TransactionInactiveError. Holen Sie externe Daten deshalb vor dem Start der Transaktion.
Nicht vorhandene Stores: Wenn transaction() einen Store-Namen bekommt, den es nicht gibt, wird ein NotFoundError geworfen. Nach close() führt jeder weitere Aufruf von transaction() zum InvalidStateError.
Verbindung sauber abgeben: close() wartet, bis laufende Transaktionen fertig sind. Behandeln Sie versionchange immer, sonst hängen Upgrades in anderen Tabs fest.
Kompatibilität: Wird in allen modernen Browsern und in Web Workern unterstützt. Die Option durability gibt es erst in neueren Versionen (Chrome 83+, Safari 15+). Firefox hat sie lange ignoriert. Im privaten Modus älterer Browser kann IndexedDB fehlen oder eingeschränkt sein.
Sicherheit: IndexedDB folgt der Same-Origin-Policy. Die Daten liegen unverschlüsselt auf dem Gerät. Speichern Sie dort keine sensiblen Geheimnisse wie Tokens ohne zusätzlichen Schutz.
Die ereignisbasierte API ist umständlich. Kleine Promise-Wrapper wie idb machen den Code deutlich lesbarer.

Siehe auch

DataCue IDBFactory IDBKeyRange IDBRequest AudioData