Your Search Results

    IDBRequest

    This article is in need of a technical review.

    « 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, 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 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.

    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.

    Inherits from: EventTarget

    Methods

    No methods.

    Properties

    IDBRequest.result Read only

    Returns the result of the request. If the the request failed and the result is not available, the InvalidStateError exception is thrown.

    IDBRequest.error Read only
    Returns the error in the event of an unsuccessful request.
    IDBRequest.source Read only
    The source of the request, such as an Index or a ObjectStore. If no source exists (such as when calling IDBFactory.open), it returns null.
    IDBRequest.transaction Read only
    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).
    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.

    Event handlers

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

    Constants

    readyState constants

    Obsolete since Gecko 25 (Firefox 25 / Thunderbird 25 / SeaMonkey 2.22)
    This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

    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; here we can see usage of the onerror and onsuccess handlers:

    var db;
    
    // Let us open our database
    var request = window.indexedDB.open("toDoList", 4);
    
    // these two event handlers act on the database being opened successfully, or not
    request.onerror = function(event) {
      note.innerHTML += '<li>Error loading database.</li>';
    };
    
    request.onsuccess = function(event) {
      note.innerHTML += '<li>Database initialised.</li>';
     
      // store the result of opening the database in the db variable.
      db = request.result;
    };

    Derived interface

    Specifications

    Specification Status Comment
    Indexed Database API Candidate Recommendation  

    Browser compatibility

    Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
    Basic support

    12 -webkit

    23

    4.0 (2.0)

    16

    10 17 Not supported
    Feature Android Firefox Mobile (Gecko) Firefox OS IE Phone Opera Mobile Safari Mobile
    Basic support 4.4 6.0 (6.0) 1.0.1 10 17 Not supported

    Be careful in Chrome as it still implements the old specification along the new one. Similarly it still has the prefixed webkitIndexedDB property even if the unprefixed indexedDB is present.

    See also

    To learn more about various topics, see the following

    • Starting transactions: IDBDatabase
    • Setting transaction modes: IDBTransaction
    • Setting a range of keys: IDBKeyRange
    • Creating cursors: IDBIndex
    • The reference application for the examples in this reference: To-do Notifications (view example live.) Not every snippet appears in this example, but every example uses the same data structure and syntax, and they will make sense in the context of this example.

    Document Tags and Contributors

    Contributors to this page: scottrowe, pdm, jswisher, chrisdavidmills, Yoshino, teoli, ian81, grendel
    Last updated by: chrisdavidmills,