W3cubDocs

IDBRequest

The IDBRequest 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 the IDBRequest instance.

All asynchronous operations immediately return an IDBRequest instance. Each request has a readyState that is set to the 'pending' state; this changes to 'done' when the request is completed or fails. When the state is set to done, every request returns a result and an error, and an event is fired on the request. When the state is still pending, any attempt to access the result or error raises an InvalidStateError exception.

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

The interface IDBOpenDBRequest is derived from IDBRequest.

Note: This feature is available in Web Workers.

Properties

Also inherits properties from EventTarget.

IDBRequest.error Read only: Returns a DOMException in the event of an unsuccessful request, indicating what went wrong.
IDBRequest.result Read only: Returns the result of the request. If the the request failed and the result is not available, an InvalidStateError exception is thrown.
IDBRequest.source Read only: The source of the request, such as an IDBIndex or an IDBObjectStore. If no source exists (such as when calling IDBFactory.open), it returns null.
IDBRequest.readyState Read only: The state of the request. Every request starts in the pending state. The state changes to done when the request completes successfully or when an error occurs.
IDBRequest.transaction Read only: The transaction for the request. This property can be null for certain requests, for example those returned from IDBFactory.open unless an upgrade is needed. (You're just connecting to a database, so there is no transaction to return).

Event handlers

IDBRequest.onerror: The event handler for the error event.
IDBRequest.onsuccess: The event handler for the success event.

Methods

No methods, but inherits methods from EventTarget.

Example

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

var db;

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

// these two event handlers act on the database being
// opened successfully, or not
DBOpenRequest.onerror = function(event) {
  note.innerHTML += '<li>Error loading database.</li>';
};

DBOpenRequest.onsuccess = function(event) {
  note.innerHTML += '<li>Database initialised.</li>';
 
  // store the result of opening the database.
  db = DBOpenRequest.result;
};

Specifications

Specification	Status	Comment
Indexed Database API The definition of 'IDBRequest' in that specification.	Recommendation	Initial definition.
Indexed Database API 2.0 The definition of 'IDBRequest' in that specification.	Recommendation

Browser compatibilityUpdate compatibility data on GitHub

	Desktop
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari
Basic support	24 24 2 — 57 Prefixed Prefixed Requires the vendor prefix: webkit	Yes	16 16 10 — 16 Prefixed Prefixed Requires the vendor prefix: moz	10 10 partial	15	7
Available in workers	Yes	?	37	?	Yes	?
`error`	24 24 23 — 57 Prefixed Prefixed Requires the vendor prefix: webkit	12	16 16 10 — 16 Prefixed Prefixed Requires the vendor prefix: moz	10 10 partial	15	7
`onerror`	24 24 23 Prefixed Prefixed Requires the vendor prefix: webkit	12	16 16 10 — 16 Prefixed Prefixed Requires the vendor prefix: moz	10 10 partial	15	7
`onsuccess`	24 24 23 Prefixed Prefixed Requires the vendor prefix: webkit	12	16 16 10 — 16 Prefixed Prefixed Requires the vendor prefix: moz	10 10 partial	15	7
`readyState`	24 24 23 Prefixed Prefixed Requires the vendor prefix: webkit	12	16 16 10 — 16 Prefixed Prefixed Requires the vendor prefix: moz	10 10 partial	15	7
`result`	24 24 23 Prefixed Prefixed Requires the vendor prefix: webkit	12	16 16 10 — 16 Prefixed Prefixed Requires the vendor prefix: moz	10 10 partial	15	7
`source`	24 24 23 Prefixed Prefixed Requires the vendor prefix: webkit	12	16 16 10 — 16 Prefixed Prefixed Requires the vendor prefix: moz	10 10 partial	15	7
`transaction`	24 24 23 Prefixed Prefixed Requires the vendor prefix: webkit	12	16 16 10 — 16 Prefixed Prefixed Requires the vendor prefix: moz	10 10 partial	15	7

	Mobile
	Android webview	Chrome for Android	Edge Mobile	Firefox for Android	Opera for Android	iOS Safari	Samsung Internet
Basic support	Yes Yes ? — 57 Prefixed Prefixed Requires the vendor prefix: webkit	25 25 25 — 57 Prefixed Prefixed Requires the vendor prefix: webkit	Yes	22	22	8	Yes Yes ? — 7.0 Prefixed Prefixed Requires the vendor prefix: webkit
Available in workers	Yes	Yes	Yes	37	Yes	?	Yes
`error`	Yes Yes ? — 57 Prefixed Prefixed Requires the vendor prefix: webkit	25 25 25 — 57 Prefixed Prefixed Requires the vendor prefix: webkit	Yes	22	22	8	Yes Yes ? — 7.0 Prefixed Prefixed Requires the vendor prefix: webkit
`onerror`	Yes	Yes	Yes	22	22	8	Yes
`onsuccess`	Yes	Yes	Yes	22	22	8	Yes
`readyState`	Yes	Yes	Yes	22	22	8	Yes
`result`	Yes	Yes	Yes	22	22	8	Yes
`source`	Yes	Yes	Yes	22	22	8	Yes
`transaction`	Yes	Yes	Yes	22	22	8	Yes