IDBTransaction

Baseline

Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

See full compatibility
Learn more

Note: This feature is available in Web Workers.

The IDBTransaction interface of the IndexedDB API provides a static, asynchronous transaction on a database using event handler attributes. All reading and writing of data is done within transactions. You use IDBDatabase to start transactions, IDBTransaction to set the mode of the transaction (e.g., is it readonly or readwrite), and you access an IDBObjectStore to make a request. You can also use an IDBTransaction object to abort transactions.

Transactions are started when the transaction is created, not when the first request is placed; for example consider this:

const trans1 = db.transaction("foo", "readwrite");
const trans2 = db.transaction("foo", "readwrite");
const objectStore2 = trans2.objectStore("foo");
const objectStore1 = trans1.objectStore("foo");
objectStore2.put("2", "key");
objectStore1.put("1", "key");

After the code is executed the object store should contain the value "2", since trans2 should run after trans1.

A transaction alternates between active and inactive states between event loop tasks. It's active in the task when it was created, and in each task of the requests' success or error event handlers. It's inactive in all other tasks, in which case placing requests will fail. If no new requests are placed when the transaction is active, and there are no other outstanding requests, the transaction will automatically commit.

Transaction failures

Transactions can fail for a fixed number of reasons, all of which (except the user agent crash) will trigger an abort callback:

Abort due to bad requests, e.g., trying to add() the same key twice, or put() with the same index key with a uniqueness constraint. This causes an error on the request, which can bubble up to an error on the transaction, which aborts the transaction. This can be prevented by using preventDefault() on the error event on the request.
An explicit abort() call from script.
An uncaught exception in the request's success/error handler.
An I/O error (e.g., an actual failure to write to disk, or other OS/hardware failure).
Quota exceeded.
A user agent crash.

Firefox durability guarantees

Note that as of Firefox 40, IndexedDB transactions have relaxed durability guarantees to increase performance (see Firefox bug 1112702.) Previously in a readwrite transaction, a complete event was fired only when all data was guaranteed to have been flushed to disk. In Firefox 40+ the complete event is fired after the OS has been told to write the data but potentially before that data has actually been flushed to disk. The complete event may thus be delivered quicker than before, however, there exists a small chance that the entire transaction will be lost if the OS crashes or there is a loss of system power before the data is flushed to disk. Since such catastrophic events are rare, most consumers should not need to concern themselves further.

If you must ensure durability for some reason (e.g., you're storing critical data that cannot be recomputed later) you can force a transaction to flush to disk before delivering the complete event by creating a transaction using the experimental (non-standard) readwriteflush mode (see IDBDatabase.transaction.

Instance properties

IDBTransaction.db Read only: The database connection with which this transaction is associated.
IDBTransaction.durability Read only: Returns the durability hint the transaction was created with.
IDBTransaction.error Read only: Returns a DOMException indicating the type of error that occurred when there is an unsuccessful transaction. This property is null if the transaction is not finished, is finished and successfully committed, or was aborted with the IDBTransaction.abort() function.
IDBTransaction.mode Read only: The mode for isolating access to data in the object stores that are in the scope of the transaction. The default value is readonly.
IDBTransaction.objectStoreNames Read only: Returns a DOMStringList of the names of IDBObjectStore objects associated with the transaction.

Instance methods

Inherits from: EventTarget

IDBTransaction.abort(): Rolls back all the changes to objects in the database associated with this transaction. If this transaction has been aborted or completed, this method fires an error event.
IDBTransaction.objectStore()