IDBRequest

BaselineWidely 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.

Note: This feature is available inWeb Workers.

TheIDBRequest interface of the IndexedDB API provides access to results of asynchronous requests to databases and database objects using event handler attributes. Each reading and writing operation on a database is done using a request.

The request object does not initially contain any information about the result of the operation, but once information becomes available, an event is fired on the request, and the information becomes available through the properties of theIDBRequest instance.

All asynchronous operations immediately return anIDBRequest instance. Each request has areadyState that is set to the'pending' state; this changes to'done' when the request is completed or fails. When the state is set todone, every request returns aresult and anerror, and an event is fired on the request. When the state is stillpending, any attempt to access theresult orerror raises anInvalidStateError exception.

In plain words, all asynchronous methods return a request object. If the request has been completed successfully, the result is made available through theresult property and an event indicating success is fired at the request (success). If an error occurs while performing the operation, the exception is made available through theerror property and an error event is fired (error).

The interfaceIDBOpenDBRequest is derived fromIDBRequest.

Instance properties

Also inherits properties fromEventTarget.

IDBRequest.errorRead only: Returns aDOMException in the event of an unsuccessful request, indicating what went wrong.
IDBRequest.resultRead only: Returns the result of the request. If the request is not completed, the result is not available and anInvalidStateError exception is thrown.
IDBRequest.sourceRead only: The source of the request, such as anIDBIndex or anIDBObjectStore. If no source exists (such as when callingIDBFactory.open), it returns null.
IDBRequest.readyStateRead only: The state of the request. Every request starts in thepending state. The state changes todone when the request completes successfully or when an error occurs.
IDBRequest.transactionRead only: The transaction for the request. This property can be null for certain requests, for example those returned fromIDBFactory.open unless an upgrade is needed. (You're just connecting to a database, so there is no transaction to return).

Instance methods

No methods, but inherits methods fromEventTarget.

Events

Listen to these events usingaddEventListener() or by assigning an event listener to theoneventname property of this interface.

error: Fired when an error caused a request to fail.
success: Fired when anIDBRequest succeeds.

Example

In the following code snippet, we open a database asynchronously and make a request;onerror andonsuccess functions are included to handle the success and error cases. For a full working example, see ourTo-do Notifications app (view example live.)

let db;// Let us open our databaseconst DBOpenRequest = window.indexedDB.open("toDoList", 4);// these two event handlers act on the database being// opened successfully, or notDBOpenRequest.onerror = (event) => {  note.appendChild(document.createElement("li")).textContent =    "Error loading database.";};DBOpenRequest.onsuccess = (event) => {  note.appendChild(document.createElement("li")).textContent =    "Database initialized.";  // store the result of opening the database.  db = DBOpenRequest.result;};