IDBTransaction

Fehler bei Transaktionen

Transaktionen können aus einer begrenzten Anzahl von Gründen fehlschlagen. Alle außer einem Absturz des User Agents lösen einen Abort-Callback aus:

• Abbruch aufgrund fehlerhafter Anfragen, z. B. wenn versucht wird, denselben Schlüssel zweimal mit add() hinzuzufügen oder put() mit demselben Indexschlüssel bei einer Eindeutigkeitsbeschränkung aufzurufen. Dadurch tritt bei der Anfrage ein Fehler auf, der sich als Fehler der Transaktion fortsetzen und diese abbrechen kann. Dies lässt sich verhindern, indem Sie beim Fehlerereignis der Anfrage preventDefault() aufrufen.
• Ein expliziter Aufruf von abort() durch ein Skript.
• Eine nicht abgefangene Ausnahme im success- oder error-Handler der Anfrage.
• Ein E/A-Fehler (z. B. ein tatsächlicher Fehler beim Schreiben auf den Datenträger oder ein anderer Fehler des Betriebssystems oder der Hardware).
• Überschreitung des Speicherkontingents.
• Ein Absturz des User Agents.

Dauerhaftigkeitsgarantien in Firefox

Beachten Sie, dass IndexedDB-Transaktionen seit Firefox 40 abgeschwächte Dauerhaftigkeitsgarantien haben, um die Leistung zu verbessern (siehe Firefox-Bug 1112702). Zuvor wurde bei einer readwrite-Transaktion ein complete-Ereignis erst ausgelöst, wenn garantiert war, dass alle Daten auf den Datenträger geschrieben worden waren. Ab Firefox 40 wird das complete-Ereignis ausgelöst, nachdem das Betriebssystem angewiesen wurde, die Daten zu schreiben – möglicherweise aber bevor die Daten tatsächlich auf den Datenträger geschrieben wurden. Das complete-Ereignis kann dadurch schneller als zuvor eintreffen. Allerdings besteht eine geringe Wahrscheinlichkeit, dass die gesamte Transaktion verloren geht, wenn das Betriebssystem abstürzt oder die Stromversorgung ausfällt, bevor die Daten auf den Datenträger geschrieben wurden. Da solche schwerwiegenden Ereignisse selten sind, müssen sich die meisten Anwender damit nicht weiter befassen.

Wenn Sie aus einem bestimmten Grund die Dauerhaftigkeit sicherstellen müssen (z. B. weil Sie kritische Daten speichern, die sich später nicht erneut berechnen lassen), können Sie erzwingen, dass die Daten einer Transaktion vor dem Auslösen des complete-Ereignisses auf den Datenträger geschrieben werden. Erstellen Sie dazu eine Transaktion im experimentellen (nicht standardisierten) Modus readwriteflush (siehe IDBDatabase.transaction).

Instanzeigenschaften

IDBTransaction.db Schreibgeschützt

Die Datenbankverbindung, der diese Transaktion zugeordnet ist.

IDBTransaction.durability Schreibgeschützt

Gibt den Dauerhaftigkeitshinweis zurück, mit dem die Transaktion erstellt wurde.

IDBTransaction.error Schreibgeschützt

Gibt bei einer fehlgeschlagenen Transaktion eine DOMException zurück, die den aufgetretenen Fehlertyp angibt. Diese Eigenschaft ist null, wenn die Transaktion noch nicht abgeschlossen ist, erfolgreich abgeschlossen wurde oder mit der Funktion IDBTransaction.abort() abgebrochen wurde.

IDBTransaction.mode Schreibgeschützt

Der Modus, mit dem der Zugriff auf Daten in den Object Stores im Geltungsbereich der Transaktion isoliert wird. Der Standardwert ist readonly.

IDBTransaction.objectStoreNames Schreibgeschützt

Gibt eine DOMStringList mit den Namen der IDBObjectStore-Objekte zurück, die der Transaktion zugeordnet sind.

Instanzmethoden

Erbt von: EventTarget

IDBTransaction.abort()

Macht alle Änderungen an Objekten in der Datenbank rückgängig, die dieser Transaktion zugeordnet sind. Wenn diese Transaktion bereits abgebrochen oder abgeschlossen wurde, löst diese Methode ein Fehlerereignis aus.

IDBTransaction.objectStore()

Gibt ein IDBObjectStore-Objekt zurück, das einen Object Store im Geltungsbereich dieser Transaktion repräsentiert.

IDBTransaction.commit()

Schließt eine aktive Transaktion ab. Beachten Sie, dass diese Methode normalerweise nicht aufgerufen werden muss: Eine Transaktion wird automatisch abgeschlossen, wenn alle ausstehenden Anfragen bearbeitet wurden und keine neuen Anfragen gestellt wurden. Mit commit() können Sie den Abschlussvorgang einleiten, ohne darauf zu warten, dass Ereignisse zu ausstehenden Anfragen ausgelöst werden.

Ereignisse

Verwenden Sie addEventListener(), um auf diese Ereignisse zu reagieren, oder weisen Sie der Eigenschaft oneventname dieser Schnittstelle einen Event Listener zu.

abort

Ein Ereignis, das ausgelöst wird, wenn die IndexedDB-Transaktion abgebrochen wird. Es ist auch über die Eigenschaft onabort verfügbar; dieses Ereignis wird an IDBDatabase weitergereicht.

complete

Ein Ereignis, das ausgelöst wird, wenn die Transaktion erfolgreich abgeschlossen wird. Es ist auch über die Eigenschaft oncomplete verfügbar.

error

Ein Ereignis, das ausgelöst wird, wenn eine Anfrage einen Fehler zurückgibt und das Ereignis bis zum Verbindungsobjekt (IDBDatabase) weitergereicht wird. Es ist auch über die Eigenschaft onerror verfügbar.

Moduskonstanten

Transaktionen können einen von drei Modi haben:

Auch wenn diese Konstanten inzwischen veraltet sind, können Sie sie bei Bedarf weiterhin verwenden, um Abwärtskompatibilität zu gewährleisten. Schreiben Sie Ihren Code defensiv für den Fall, dass das Objekt nicht mehr verfügbar ist:

const myIDBTransaction = window.IDBTransaction ||
  window.webkitIDBTransaction || { READ_WRITE: "readwrite" };

Beispiele

Im folgenden Codeausschnitt öffnen wir eine Lese-/Schreibtransaktion für unsere Datenbank und fügen einem Object Store einige Daten hinzu. Beachten Sie auch die Funktionen, die den Event-Handlern der Transaktion zugewiesen sind: Sie melden, ob die Transaktion erfolgreich geöffnet wurde oder fehlgeschlagen ist. Ein vollständiges, funktionsfähiges Beispiel finden Sie in unserer App To-do Notifications (Beispiel live ansehen).

const note = document.getElementById("notifications");

// an instance of a db object for us to store the IDB data in
let db;

// Let us open our database
const DBOpenRequest = window.indexedDB.open("toDoList", 4);

DBOpenRequest.onsuccess = (event) => {
  note.appendChild(document.createElement("li")).textContent =
    "Database initialized.";

  // store the result of opening the database in the db
  // variable. This is used a lot below
  db = DBOpenRequest.result;

  // Add the data to the database
  addData();
};

function addData() {
  // Create a new object to insert into the IDB
  const newItem = [
    {
      taskTitle: "Walk dog",
      hours: 19,
      minutes: 30,
      day: 24,
      month: "December",
      year: 2013,
      notified: "no",
    },
  ];

  // open a read/write db transaction, ready to add data
  const transaction = db.transaction(["toDoList"], "readwrite");

  // report on the success of opening the transaction
  transaction.oncomplete = (event) => {
    note.appendChild(document.createElement("li")).textContent =
      "Transaction completed: database modification finished.";
  };

  transaction.onerror = (event) => {
    note.appendChild(document.createElement("li")).textContent =
      "Transaction not opened due to error. Duplicate items not allowed.";
  };

  // create an object store on the transaction
  const objectStore = transaction.objectStore("toDoList");

  // add our newItem object to the object store
  const objectStoreRequest = objectStore.add(newItem[0]);

  objectStoreRequest.onsuccess = (event) => {
    // report the success of the request (this does not mean the item
    // has been stored successfully in the DB - for that you need transaction.oncomplete)
    note.appendChild(document.createElement("li")).textContent =
      "Request successful.";
  };
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• IndexedDB verwenden
• Transaktionen starten: IDBDatabase
• Einen Schlüsselbereich festlegen: IDBKeyRange
• Daten abrufen und ändern: IDBObjectStore
• Cursor verwenden: IDBCursor
• Referenzbeispiel: To-do Notifications (Beispiel live ansehen).