IDBTransaction

Transaktionsfehler

Transaktionen können aus einer festgelegten Anzahl von Gründen fehlschlagen; alle davon (außer einem Absturz des User Agents) lösen einen Abort-Callback aus:

• Abbruch aufgrund fehlerhafter Anfragen, z. B. beim Versuch, denselben Schlüssel zweimal mit add() hinzuzufügen, oder bei put() mit demselben Indexschlüssel bei einer Eindeutigkeitsbeschränkung. Dies verursacht einen Fehler bei der Anfrage, der zu einem Fehler bei der Transaktion weitergereicht werden kann, wodurch die Transaktion abgebrochen wird. Dies kann verhindert werden, indem preventDefault() für das Fehlerereignis der Anfrage verwendet wird.
• Ein expliziter abort()-Aufruf durch ein Skript.
• Eine nicht abgefangene Ausnahme im success/error-Handler der Anfrage.
• Ein E/A-Fehler (z. B. ein tatsächlicher Fehler beim Schreiben auf die Festplatte oder ein anderer Betriebssystem-/Hardwarefehler).
• Überschrittenes Kontingent.
• Ein Absturz des User Agents.

Firefox-Dauerhaftigkeitsgarantien

Beachten Sie, dass IndexedDB-Transaktionen seit Firefox 40 gelockerte Dauerhaftigkeitsgarantien haben, um die Leistung zu erhöhen (siehe Firefox-Bug 1112702.) Zuvor wurde bei einer readwrite-Transaktion ein complete-Ereignis erst ausgelöst, wenn garantiert war, dass alle Daten auf die Festplatte geschrieben wurden. In Firefox 40+ wird das complete-Ereignis ausgelöst, nachdem das Betriebssystem angewiesen wurde, die Daten zu schreiben, jedoch möglicherweise bevor diese Daten tatsächlich auf die Festplatte geschrieben wurden. Das complete-Ereignis kann daher schneller als zuvor ausgeliefert werden; 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 die Festplatte geschrieben wurden. Da solche katastrophalen Ereignisse selten sind, müssen sich die meisten Nutzenden nicht weiter darum kümmern.

Wenn Sie aus irgendeinem Grund Dauerhaftigkeit sicherstellen müssen (z. B. weil Sie kritische Daten speichern, die später nicht neu berechnet werden können), können Sie eine Transaktion dazu zwingen, vor der Auslieferung des complete-Ereignisses auf die Festplatte zu schreiben, indem Sie eine Transaktion mit dem experimentellen (nicht standardmäßigen) Modus readwriteflush erstellen (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 eine DOMException zurück, die den Fehlertyp angibt, der bei einer nicht erfolgreichen Transaktion aufgetreten ist. Diese Eigenschaft ist null, wenn die Transaktion nicht abgeschlossen ist, abgeschlossen und erfolgreich festgeschrieben wurde oder mit der Funktion IDBTransaction.abort() abgebrochen wurde.

IDBTransaction.mode Schreibgeschützt

Der Modus zur Isolierung des Zugriffs auf Daten in den Object Stores, die zum Geltungsbereich der Transaktion gehören. 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

Geerbt von: EventTarget

IDBTransaction.abort()

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

IDBTransaction.objectStore()

Gibt ein IDBObjectStore-Objekt zurück, das einen Object Store darstellt, der Teil des Geltungsbereichs dieser Transaktion ist.

IDBTransaction.commit()

Schreibt bei einer aktiven Transaktion die Transaktion fest. Beachten Sie, dass dies normalerweise nicht aufgerufen werden muss — eine Transaktion wird automatisch festgeschrieben, wenn alle ausstehenden Anfragen erfüllt wurden und keine neuen Anfragen gestellt wurden. commit() kann verwendet werden, um den Festschreibungsprozess zu starten, ohne darauf zu warten, dass Ereignisse ausstehender Anfragen ausgeliefert werden.

Ereignisse

Überwachen Sie diese Ereignisse mit addEventListener() oder indem Sie der Eigenschaft oneventname dieser Schnittstelle einen Event Listener zuweisen.

abort

Ein Ereignis, das ausgelöst wird, wenn die IndexedDB-Transaktion abgebrochen wird. 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. Auch über die Eigenschaft oncomplete verfügbar.

error

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

Moduskonstanten

Transaktionen können einen von drei Modi haben:

Auch wenn diese Konstanten jetzt veraltet sind, können Sie sie bei Bedarf weiterhin verwenden, um Abwärtskompatibilität bereitzustellen. Sie sollten defensiv programmieren, falls 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 an die Event-Handler der Transaktion angehängt sind, um bei Erfolg oder Fehlschlag über das Ergebnis des Öffnens der Transaktion zu berichten. Ein vollständiges funktionierendes 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
• Ihre Daten abrufen und ändern: IDBObjectStore
• Cursor verwenden: IDBCursor
• Referenzbeispiel: To-do Notifications (Beispiel live ansehen).