{{APIRef("IndexedDB")}}
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 {{domxref("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.
{{AvailableInWorkers}}
Note: 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 ({{domxref("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 ({{domxref("IDBRequest.onerror")}}).
Note: IDBRequest
inherits from EventTarget; {{domxref("IDBOpenDBRequest")}} is derived from it.
Methods
No methods.
Properties
- {{domxref("IDBRequest.result")}} {{readonlyInline}}
-
Returns the result of the request. If the the request failed and the result is not available, an InvalidStateError exception is thrown.
- {{domxref("IDBRequest.error")}} {{readonlyInline}}
- Returns an error in the event of an unsuccessful request, indicating what went wrong.
- {{domxref("IDBRequest.source")}} {{readonlyInline}}
- The source of the request, such as an {{domxref("IDBIndex")}} or an {{domxref("IDBObjectStore")}}. If no source exists (such as when calling {{domxref("IDBFactory.open")}}), it returns null.
- {{domxref("IDBRequest.transaction")}} {{readonlyInline}}
- The transaction for the request. This property can be null for certain requests, for example those returned from {{domxref("IDBFactory.open")}} (You're just connecting to a database, so there is no transaction to return).
- {{domxref("IDBRequest.readyState")}} {{readonlyInline}}
- The state of the request. Every request starts in the
pending
state. The state changes todone
when the request completes successfully or when an error occurs.
Event handlers
- {{domxref("IDBRequest.onerror")}}
- The event handler for the error event.
- {{domxref("IDBRequest.onsuccess")}}
- The event handler for the success event.
Constants
readyState
constants
These constants are no longer available. You should use the direct string constants instead. ({{ bug(887524) }})
Constant | Value | Description |
---|---|---|
DONE |
"done" | The request has completed or an error has occurred. Initially false |
LOADING |
"pending" | The request has been started, but its result is not yet available. |
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 in the db variable. db = DBOpenRequest.result; };
Specifications
Specification | Status | Comment |
---|---|---|
{{SpecName('IndexedDB', '#idl-def-IDBRequest', 'IDBRequest')}} | {{Spec2('IndexedDB')}} |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support | 23{{property_prefix("webkit")}} 24 |
10 {{property_prefix("moz")}} {{CompatGeckoDesktop("16.0")}} |
10, partial | 15 | 7.1 |
Available in workers | {{CompatVersionUnknown}} | {{CompatGeckoMobile("37.0")}} | {{CompatUnknown}} | {{CompatVersionUnknown}} | {{CompatUnknown}} |
Feature | Android | Firefox Mobile (Gecko) | Firefox OS | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | 4.4 | {{CompatGeckoMobile("22.0")}} | 1.0.1 | 10 | 22 | 8 |
Available in workers | {{CompatVersionUnknown}} | {{CompatGeckoMobile("37.0")}} | {{CompatVersionUnknown}} | {{CompatUnknown}} | {{CompatVersionUnknown}} | {{CompatUnknown}} |
Be careful in Chrome as it still implements the old specification along with the new one. Similarly it still has the prefixed webkitIndexedDB
property even if the unprefixed indexedDB
is present.
See also
- Using IndexedDB
- Starting transactions: {{domxref("IDBDatabase")}}
- Using transactions: {{domxref("IDBTransaction")}}
- Setting a range of keys: {{domxref("IDBKeyRange")}}
- Retrieving and making changes to your data: {{domxref("IDBObjectStore")}}
- Using cursors: {{domxref("IDBCursor")}}
- Reference example: To-do Notifications (view example live.)