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.

Inherits from: EventTarget

About this document

This document was last updated on September 23, 2011 and follows the W3C Specifications (Editor's Draft) drafted on September 22, 2011. It has not yet been verified.

Basic concepts

All asynchronous operations immediately return an IDBRequest instance. Each request has a readyState that is set to the LOADING state, which then changes to DONE when the request is completed or fails. When the state is set to DONE, every request returns a result and an errorCode, and an event is fired on the request. When the state is still LOADING, any attempt to access the result or errorCode raises a NOT_ALLOWED_ERR exception.

All that is saying in plain English is that: 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. If an error occurs while performing the operation, the exception is made available through the result property and an error event is fired.

Example

In the following code snippet, we open a database asynchronously and make a request. Event handlers are registered for responding to various situations.

var request = window.indexedDB.open('Database Name');
request.onsuccess = function(event) {
        var db = this.result;
        var transaction = db.transaction([], IDBTransaction.READ_ONLY);
        var curRequest = transaction.objectStore('ObjectStore Name').openCursor();
        curRequest.onsuccess = ...;
    };
request.onerror = function(event) {
         ...;
    };

Attributes



Attribute Type Description
result readonly any

Returns the result of the request.

If the the request failed and the result is not available, the NOT_ALLOWED_ERR exception is thrown.

errorCode readonly unsigned short

The following error codes are returned under certain conditions:

  • ABORT_ERR — If you abort the transaction, then all requests still in progress receive this error.
  • CONSTRAINT_ERR — If you insert data that doesn't conform to a constraint. It's an exception type for creating stores and indexes. You get this error, for example, if you try to add a new key that already exists in the record.
  • QUOTA_ERR — If you run out of disk quota and the user declined to grant you more space.
  • UNKNOWN_ERR — If the operation failed for reasons unrelated to the database itself. A failure due to disk IO errors is such an example.
  • NO_ERR — If the request succeeds.
  • VERSION_ERR — If you try to open a database with a version lower than the one it already has.

In addition to the error codes sent to the IDBRequest object, asynchronous operations can also raise exceptions. The list describes problems that could occur when the request is being executed, but you might also encounter other problems when the request is being made. For more information on all error codes that could occur, see IDBDatabaseException.

source readonly Object

The source of the request, such as an Index or a ObjectStore. If no source exists (such as when calling indexedDB.open()), it returns null.

transaction readonly IDBTransaction The transaction for the request. This property can be null for certain requests, such as for request returned from IDBFactory.open (You're just connecting to a database, so there is no transaction to return).
readyState readonly unsigned short

The state of the request. Every request starts in the LOADING state. The state changes to DONE when the request completes successfully or when an error occurs.

onerror Function The event handler for the error event.
onsuccess Function The event handler for the success event.

Constants

readyState constants

Constant Value Description
DONE
2 The request has completed or an error has occurred. Initially false
LOADING
1 The request has been started, but its result is not yet available.

Event handlers

Event handler Event handler type
onerror error
onsuccess success

Derived interface

Browser compatibility

  • Desktop
  • Mobile

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 12 -webkit 4.0 (2.0) -- -- --
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support -- 6.0 (6.0) ? -- --

Tags (1)

Edit tags

Attachments (0)

 

Attach file