4.1. The IDBRequest interface

The [IDBRequest](#idbrequest) interface provides the means to access results of asynchronous requests to databases and database objects using event handler IDL attributes [HTML52].

Every method for making asynchronous requests returns an [IDBRequest](#idbrequest) object that communicates back to the requesting application through events. This design means that any number of requests can be active on any database at a time.

In the following example, we open a database asynchronously. Various event handlers are registered for responding to various situations.

  1. var request = indexedDB.open('AddressBook', 15);
  2. request.onsuccess = function(evt) {...};
  3. request.onerror = function(evt) {...};
  1. [Exposed=(Window,Worker)]
  2. interface IDBRequest : EventTarget {
  3.   readonly attribute any result;
  4.   readonly attribute DOMException? error;
  5.   readonly attribute (IDBObjectStore or IDBIndex or IDBCursor)? source;
  6.   readonly attribute IDBTransaction? transaction;
  7.   readonly attribute IDBRequestReadyState readyState;
  8.  
  9.   // Event handlers:
  10.   attribute EventHandler onsuccess;
  11.   attribute EventHandler onerror;
  12. };
  13.  
  14. enum IDBRequestReadyState {
  15.   "pending",
  16.   "done"
  17. };

request . [result](#dom-idbrequest-result)

When a request is completed, returns the result, or undefined if the request failed. Throws a “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) if the request is still pending.

request . [error](#dom-idbrequest-error)

When a request is completed, returns the error (a [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException)), or null if the request succeeded. Throws a “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) if the request is still pending.

request . [source](#dom-idbrequest-source)

Returns the [IDBObjectStore](#idbobjectstore), [IDBIndex](#idbindex), or [IDBCursor](#idbcursor) the request was made against, or null if is was an open request.

request . [transaction](#dom-idbrequest-transaction)

Returns the [IDBTransaction](#idbtransaction) the request was made within. If this as an open request, then it returns an upgrade transaction while it is running, or null otherwise.

request . [readyState](#dom-idbrequest-readystate)

Returns ["pending"](#dom-idbrequestreadystate-pending) until a request is complete, then returns ["done"](#dom-idbrequestreadystate-done).

The result attribute’s getter must throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) if the done flag is unset. Otherwise, the attribute’s getter must return the result of the request, or undefined if the request resulted in an error.

The error attribute’s getter must throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) if the done flag is unset. Otherwise, the attribute’s getter must return the error of the request, or null if no error occurred.

The source attribute’s getter must return the source of the request, or null if no source is set.

The transaction attribute’s getter must return the transaction of the request. This property can be null for certain requests, such as for requests returned from [open()](#dom-idbfactory-open).

The readyState attribute’s getter must return ["pending"](#dom-idbrequestreadystate-pending) if the done flag is unset, and ["done"](#dom-idbrequestreadystate-done) otherwise.

The onsuccess attribute is the event handler for the success event.

The onerror attribute is the event handler for the error event.

Methods on [IDBDatabase](#idbdatabase) that return a open request use an extended interface to allow listening to the [blocked](#request-blocked) event and [upgradeneeded](#request-upgradeneeded) event.

  1. [Exposed=(Window,Worker)]
  2. interface IDBOpenDBRequest : IDBRequest {
  3.   // Event handlers:
  4.   attribute EventHandler onblocked;
  5.   attribute EventHandler onupgradeneeded;
  6. };

The onblocked attribute is the event handler for the [blocked](#request-blocked) event.

The onupgradeneeded attribute is the event handler for the [upgradeneeded](#request-upgradeneeded) event.