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.
<div id="interfaceDiagram" style="display: inline-block; position: relative; width: 100%; padding-bottom: 11.666666666666666%; vertical-align: middle; overflow: hidden;"><svg style="display: inline-block; position: absolute; top: 0; left: 0;" viewbox="-50 0 600 70" preserveAspectRatio="xMinYMin meet"><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget" target="_top"><rect x="1" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text x="56" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">EventTarget</text></a><polyline points="111,25 121,20 121,30 111,25" stroke="#D4DDE4" fill="none"/><line x1="121" y1="25" x2="151" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/IDBRequest" target="_top"><rect x="151" y="1" width="100" height="50" fill="#F4F7F8" stroke="#D4DDE4" stroke-width="2px" /><text x="201" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">IDBRequest</text></a></svg></div>
a:hover text { fill: #0095DD; pointer-events: all;}
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 anIDBObjectStore
. If no source exists (such as when callingIDBFactory.open
), it returns null. IDBRequest.readyState
Read only- 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. 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).
Methods
No methods, but inherits methods from EventTarget
.
Events
Listen to these events using addEventListener()
or by assigning an event listener to the oneventname
property of this interface.
error
- Fired when an error caused a request to fail. Also available via the
onerror
property. success
- Fired when an
IDBRequest
succeeds. Also available via theonsuccess
property.
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 2.0The definition of 'IDBRequest' in that specification. | Recommendation | Initial definition. |
Indexed Database API DraftThe definition of 'IDBRequest' in that specification. | Recommendation |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
IDBRequest
|
Chrome Full support 24 Full support 24 No support 2 — 57 Prefixed' Implemented with the vendor prefix: webkit |
Edge
Full support 12 |
Firefox Full support 16 Full support 16 No support 10 — 16 Prefixed' Implemented with the vendor prefix: moz |
IE
Partial support 10 |
Opera
Full support 15 |
Safari
Full support 7 |
WebView Android Full support Yes Full support Yes No support ? — 57 Prefixed' Implemented with the vendor prefix: webkit |
Chrome Android Full support 25 Full support 25 No support 25 — 57 Prefixed' Implemented with the vendor prefix: webkit |
Firefox Android
Full support 22 |
Opera Android
Full support 14 |
Safari iOS
Full support 8 |
Samsung Internet Android Full support 1.5 Full support 1.5 No support 1.5 — 7.0 Prefixed' Implemented with the vendor prefix: webkit |
error
|
Chrome Full support 24 Full support 24 No support 23 — 57 Prefixed' Implemented with the vendor prefix: webkit |
Edge
Full support 12 |
Firefox Full support 16 Full support 16 No support 10 — 16 Prefixed' Implemented with the vendor prefix: moz |
IE
Partial support 10 |
Opera
Full support 15 |
Safari
Full support 7 |
WebView Android Full support Yes Full support Yes No support ? — 57 Prefixed' Implemented with the vendor prefix: webkit |
Chrome Android Full support 25 Full support 25 No support 25 — 57 Prefixed' Implemented with the vendor prefix: webkit |
Firefox Android
Full support 22 |
Opera Android
Full support 14 |
Safari iOS
Full support 8 |
Samsung Internet Android Full support 1.5 Full support 1.5 No support 1.5 — 7.0 Prefixed' Implemented with the vendor prefix: webkit |
error event
|
Chrome Full support 24 Full support 24 Full support 23 Prefixed' Implemented with the vendor prefix: webkit |
Edge
Full support 12 |
Firefox Full support 16 Full support 16 No support 10 — 16 Prefixed' Implemented with the vendor prefix: moz |
IE
Partial support 10 |
Opera
Full support 15 |
Safari
Full support 7 |
WebView Android
Full support Yes |
Chrome Android
Full support Yes |
Firefox Android
Full support 22 |
Opera Android
Full support 14 |
Safari iOS
Full support 8 |
Samsung Internet Android
Full support Yes |
onerror
|
Chrome Full support 24 Full support 24 Full support 23 Prefixed' Implemented with the vendor prefix: webkit |
Edge
Full support 12 |
Firefox Full support 16 Full support 16 No support 10 — 16 Prefixed' Implemented with the vendor prefix: moz |
IE
Partial support 10 |
Opera
Full support 15 |
Safari
Full support 7 |
WebView Android
Full support Yes |
Chrome Android
Full support Yes |
Firefox Android
Full support 22 |
Opera Android
Full support 14 |
Safari iOS
Full support 8 |
Samsung Internet Android
Full support Yes |
onsuccess
|
Chrome Full support 24 Full support 24 Full support 23 Prefixed' Implemented with the vendor prefix: webkit |
Edge
Full support 12 |
Firefox Full support 16 Full support 16 No support 10 — 16 Prefixed' Implemented with the vendor prefix: moz |
IE
Partial support 10 |
Opera
Full support 15 |
Safari
Full support 7 |
WebView Android
Full support Yes |
Chrome Android
Full support Yes |
Firefox Android
Full support 22 |
Opera Android
Full support 14 |
Safari iOS
Full support 8 |
Samsung Internet Android
Full support Yes |
readyState
|
Chrome Full support 24 Full support 24 Full support 23 Prefixed' Implemented with the vendor prefix: webkit |
Edge
Full support 12 |
Firefox Full support 16 Full support 16 No support 10 — 16 Prefixed' Implemented with the vendor prefix: moz |
IE
Partial support 10 |
Opera
Full support 15 |
Safari
Full support 7 |
WebView Android
Full support Yes |
Chrome Android
Full support Yes |
Firefox Android
Full support 22 |
Opera Android
Full support 14 |
Safari iOS
Full support 8 |
Samsung Internet Android
Full support Yes |
result
|
Chrome Full support 24 Full support 24 Full support 23 Prefixed' Implemented with the vendor prefix: webkit |
Edge
Full support 12 |
Firefox Full support 16 Full support 16 No support 10 — 16 Prefixed' Implemented with the vendor prefix: moz |
IE
Partial support 10 |
Opera
Full support 15 |
Safari
Full support 7 |
WebView Android
Full support Yes |
Chrome Android
Full support Yes |
Firefox Android
Full support 22 |
Opera Android
Full support 14 |
Safari iOS
Full support 8 |
Samsung Internet Android
Full support Yes |
source
|
Chrome Full support 24 Full support 24 Full support 23 Prefixed' Implemented with the vendor prefix: webkit |
Edge
Full support 12 |
Firefox Full support 16 Full support 16 No support 10 — 16 Prefixed' Implemented with the vendor prefix: moz |
IE
Partial support 10 |
Opera
Full support 15 |
Safari
Full support 7 |
WebView Android
Full support Yes |
Chrome Android
Full support Yes |
Firefox Android
Full support 22 |
Opera Android
Full support 14 |
Safari iOS
Full support 8 |
Samsung Internet Android
Full support Yes |
success event
|
Chrome Full support 24 Full support 24 Full support 23 Prefixed' Implemented with the vendor prefix: webkit |
Edge
Full support 12 |
Firefox Full support 16 Full support 16 No support 10 — 16 Prefixed' Implemented with the vendor prefix: moz |
IE
Partial support 10 |
Opera
Full support 15 |
Safari
Full support 7 |
WebView Android
Full support Yes |
Chrome Android
Full support Yes |
Firefox Android
Full support 22 |
Opera Android
Full support 14 |
Safari iOS
Full support 8 |
Samsung Internet Android
Full support Yes |
transaction
|
Chrome Full support 24 Full support 24 Full support 23 Prefixed' Implemented with the vendor prefix: webkit |
Edge
Full support 12 |
Firefox Full support 16 Full support 16 No support 10 — 16 Prefixed' Implemented with the vendor prefix: moz |
IE
Partial support 10 |
Opera
Full support 15 |
Safari
Full support 7 |
WebView Android
Full support Yes |
Chrome Android
Full support Yes |
Firefox Android
Full support 22 |
Opera Android
Full support 14 |
Safari iOS
Full support 8 |
Samsung Internet Android
Full support Yes |
Available in workers | Chrome
Full support Yes |
Edge
Full support ≤79 |
Firefox
Full support 37 |
IE
? |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support Yes |
Chrome Android
Full support Yes |
Firefox Android
Full support 37 |
Opera Android
Full support Yes |
Safari iOS
? |
Samsung Internet Android
Full support Yes |
Legend
- Full support
- Full support
- Partial support
- Partial support
- Compatibility unknown
- Compatibility unknown
- Requires a vendor prefix or different name for use.'
- Requires a vendor prefix or different name for use.
See also
- Using IndexedDB
- Starting transactions:
IDBDatabase
- Using transactions:
IDBTransaction
- Setting a range of keys:
IDBKeyRange
- Retrieving and making changes to your data:
IDBObjectStore
- Using cursors:
IDBCursor
- Reference example: To-do Notifications ([[../../../../../../mdn.github.io/to-do-notifications/index|view example live]].)
IDBRequest by Mozilla Contributors is licensed under CC-BY-SA 2.5.