Revision 914149 of IDBRequest

<p>{{APIRef("IndexedDB")}}</p>

<div>
<p>The <code>IDBRequest</code> 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.</p>
</div>

<p>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 <code>IDBRequest</code> instance.</p>

<p>All asynchronous operations immediately return an {{domxref("IDBRequest")}} instance. Each request has a <code>readyState</code> that is set to the <font face="Courier New, Andale Mono, monospace"><span style="line-height: normal;">pending</span></font> state; this changes to <code><a href="#const_done">d</a>one</code> when the request is completed or fails. When the state is set to <code>done</code>, every request returns a <code>result</code> and an <code>error</code>, and an event is fired on the request. When the state is still <code>pending</code>, any attempt to access the <code>result</code> or <code>error</code> raises an <code>InvalidStateError</code> exception.</p>

<div class="note">
<p><strong>Note</strong>: In plain words, all asynchronous methods return a request object. If the request has been completed successfully, the result is made available through the <code>result</code> 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 <code>result</code> property and an error event is fired ({{domxref("IDBRequest.onerror")}}).</p>
</div>

<div class="note">
<p><strong>Note</strong>: <code>IDBRequest</code> inherits from <a href="/en/DOM/EventTarget" title="en/DOM/EventTarget">EventTarget</a>; <span style="line-height: 1.5;">{{domxref("IDBOpenDBRequest")}} is derived from it.</span></p>
</div>

<h2 id="Methods">Methods</h2>

<p>No methods.</p>

<h2 id="Properties">Properties</h2>

<dl>
 <dt>{{domxref("IDBRequest.result")}} {{readonlyInline}}</dt>
 <dd>
 <p>Returns the result of the request. If the the request failed and the result is not available, an <span style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;">InvalidStateError</span> exception is thrown.</p>
 </dd>
 <dt>{{domxref("IDBRequest.error")}} {{readonlyInline}}</dt>
 <dd>Returns an error in the event of an unsuccessful request, indicating what went wrong.</dd>
 <dt>{{domxref("IDBRequest.source")}} {{readonlyInline}}</dt>
 <dd>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.</dd>
 <dt>{{domxref("IDBRequest.transaction")}} {{readonlyInline}}</dt>
 <dd>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).</dd>
 <dt>{{domxref("IDBRequest.readyState")}} {{readonlyInline}}</dt>
 <dd>The state of the request. Every request starts in the <code>pending</code> state. The state changes to <code>done</code> when the request completes successfully or when an error occurs.</dd>
</dl>

<h3 id="Event_handlers">Event handlers</h3>

<dl>
 <dt>{{domxref("IDBRequest.onerror")}}</dt>
 <dd>The event handler for the error event.</dd>
 <dt>{{domxref("IDBRequest.onsuccess")}}</dt>
 <dd>The event handler for the success event.</dd>
</dl>

<h2 id="Constants">Constants</h2>

<h3 id="readyState_constants"><code>readyState</code> constants</h3>

<div>{{ obsolete_header(25) }}</div>

<div class="warning">
<p>These constants are no longer available. You should use the direct string constants instead. ({{ bug(887524) }})</p>
</div>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Constant</th>
   <th scope="col">Value</th>
   <th scope="col">Description</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code><a name="const_done">DONE</a></code></td>
   <td>"done"</td>
   <td>The request has completed or an error has occurred. Initially false</td>
  </tr>
  <tr>
   <td><code><a name="const_loading">LOADING</a></code></td>
   <td>"pending"</td>
   <td>The request has been started, but its result is not yet available.</td>
  </tr>
 </tbody>
</table>

<h2 id="Example">Example</h2>

<p>In the following code snippet, we open a database asynchronously and make a request; <code>onerror</code> and <code>onsuccess</code> functions are included to handle the success and error cases. For a full working example, see our <a class="external" href="https://github.com/chrisdavidmills/to-do-notifications/tree/gh-pages" style="line-height: 1.5;">To-do Notifications</a><span style="line-height: 1.5;"> app (</span><a class="external" href="https://chrisdavidmills.github.io/to-do-notifications/" style="line-height: 1.5;">view example live</a><span style="line-height: 1.5;">.) </span></p>

<pre class="brush: js;highlight:[4,7,8,9,11,12,13,14,15,16]">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 += '&lt;li&gt;Error loading database.&lt;/li&gt;';
};

DBOpenRequest.onsuccess = function(event) {
  note.innerHTML += '&lt;li&gt;Database initialised.&lt;/li&gt;';
 
  // store the result of opening the database in the db variable.
  db = DBOpenRequest.result;
};</pre>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('IndexedDB', '#idl-def-IDBRequest', 'IDBRequest')}}</td>
   <td>{{Spec2('IndexedDB')}}</td>
   <td> </td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility" name="Browser_compatibility">Browser compatibility</h2>

<div>{{CompatibilityTable}}</div>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>23{{property_prefix("webkit")}}<br>
    24</td>
   <td>10 {{property_prefix("moz")}}<br>
    {{CompatGeckoDesktop("16.0")}}</td>
   <td>10, partial</td>
   <td>15</td>
   <td>7.1</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>Firefox OS</th>
   <th>IE Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>4.4</td>
   <td>{{CompatGeckoMobile("22.0")}}</td>
   <td>1.0.1</td>
   <td>10</td>
   <td>22</td>
   <td>{{CompatNo}}</td>
  </tr>
 </tbody>
</table>
</div>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB">Using IndexedDB</a></li>
 <li>Starting transactions: {{domxref("IDBDatabase")}}</li>
 <li>Using transactions: {{domxref("IDBTransaction")}}</li>
 <li>Setting a range of keys: {{domxref("IDBKeyRange")}}</li>
 <li>Retrieving and making changes to your data: {{domxref("IDBObjectStore")}}</li>
 <li>Using cursors: {{domxref("IDBCursor")}}</li>
 <li>Reference example: <a class="external" href="https://github.com/mdn/to-do-notifications/tree/gh-pages">To-do Notifications</a> (<a class="external" href="https://mdn.github.io/to-do-notifications/">view example live</a>.)</li>
</ul>