---
title: IDBDatabase
slug: Web/API/IDBDatabase
tags:
  - API
  - Database
  - IDBDatabase
  - IndexedDB
  - Interface
  - NeedsTranslation
  - Reference
  - Storage
  - TopicStub
  - accessing data
  - asynchronous access
  - transactions
translation_of: Web/API/IDBDatabase
---
<p>{{APIRef("IndexedDB")}}</p>

<div>
<p>The <strong><code>IDBDatabase</code></strong> interface of the IndexedDB API provides a <a href="/en-US/docs/IndexedDB#database_connection">connection to a database</a>; you can use an <code>IDBDatabase</code> object to open a <a href="/en-US/docs/IndexedDB#gloss_transaction">transaction</a> on your database then create, manipulate, and delete objects (data) in that database. The interface provides the only way to get and manage versions of the database.</p>

<p>{{AvailableInWorkers}}</p>
</div>

<div class="note">
<p><strong>Note</strong>: Everything you do in IndexedDB always happens in the context of a <a href="/en-US/docs/IndexedDB/Basic_Concepts_Behind_IndexedDB#gloss_transaction">transaction</a>, representing interactions with data in the database. All objects in IndexedDB — including object stores, indexes, and cursors — are tied to a particular transaction. Thus, you cannot execute commands, access data, or open anything outside of a transaction.</p>
</div>

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

<p>Inherits from: <a href="/en-US/docs/DOM/EventTarget">EventTarget</a></p>

<dl>
 <dt>{{domxref("IDBDatabase.close()")}}</dt>
 <dd>Returns immediately and closes the connection to a database in a separate thread.</dd>
 <dt>{{domxref("IDBDatabase.createObjectStore()")}}</dt>
 <dd>Creates and returns a new object store or index.</dd>
 <dt>{{domxref("IDBDatabase.deleteObjectStore()")}}</dt>
 <dd>Destroys the object store with the given name in the connected database, along with any indexes that reference it.</dd>
 <dt>{{domxref("IDBDatabase.transaction()")}}</dt>
 <dd>Immediately returns a transaction object ({{domxref("IDBTransaction")}}) containing the {{domxref("IDBTransaction.objectStore")}} method, which you can use to access your object store. Runs in a separate thread.</dd>
</dl>

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

<dl>
 <dt>{{domxref("IDBDatabase.name")}} {{readonlyInline}}</dt>
 <dd>A {{ domxref("DOMString") }} that contains the name of the connected database.</dd>
 <dt>{{domxref("IDBDatabase.version")}} {{readonlyInline}}</dt>
 <dd>A <a href="/en-US/docs/NSPR_API_Reference/Long_Long_(64-bit)_Integers">64-bit integer</a> that contains the version of the connected database. When a database is first created, this attribute is an empty string.</dd>
 <dt>{{domxref("IDBDatabase.objectStoreNames")}} {{readonlyInline}}</dt>
 <dd>A {{ domxref("DOMStringList") }} that contains a list of the names of the <a href="/en-US/docs/IndexedDB#gloss_object_store">object stores</a> currently in the connected database.</dd>
</dl>

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

<dl>
 <dt>{{domxref("IDBDatabase.onabort")}}</dt>
 <dd>Fires when access of the database is aborted.</dd>
 <dt>{{domxref("IDBDatabase.onclose")}}</dt>
 <dd>Fires when the {{event("close")}} event occurs; this happens when the database is unexpectedly closed, such as during application shutdown.</dd>
 <dt>{{domxref("IDBDatabase.onerror")}}</dt>
 <dd>Fires when access to the database fails.</dd>
 <dt>{{domxref("IDBDatabase.onversionchange")}}</dt>
 <dd>
 <p>Fires when a database structure change ({{domxref("IDBOpenDBRequest.onupgradeneeded")}} event or<code> </code>{{domxref("IDBFactory.deleteDatabase()")}} was requested elsewhere (most probably in another window/tab on the same computer). This is different from the version change transaction (see {{domxref("IDBVersionChangeEvent")}}), but it is related.</p>
 </dd>
</dl>

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

<p>In the following code snippet, we open a database asynchronously ({{domxref("IDBFactory")}}), handle success and error cases, and create a new object store in the case that an upgrade is needed ({{ domxref("IDBdatabase") }}). For a complete working example, see our <a href="https://github.com/mdn/to-do-notifications/">To-do Notifications</a> app (<a href="http://mdn.github.io/to-do-notifications/">view example live</a>.)</p>

<pre class="brush: js;highlight:[13,24,26,27,28,32]">// Let us open our database
  var DBOpenRequest = window.indexedDB.open("toDoList", 4);

  // these two event handlers act on the IDBDatabase object, when the database is 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. This is used a lot later on
    db = DBOpenRequest.result;

    // Run the displayData() function to populate the task list with all the to-do list data already in the IDB
    displayData();
  };

  // This event handles the event whereby a new version of the database needs to be created
  // Either one has not been created before, or a new version number has been submitted via the
  // window.indexedDB.open line above

  DBOpenRequest.onupgradeneeded = function(event) {
    var db = event.target.result;

    db.onerror = function(event) {
      note.innerHTML += '&lt;li&gt;Error loading database.&lt;/li&gt;';
    };

    // Create an objectStore for this database using IDBDatabase.createObjectStore

    var objectStore = db.createObjectStore("toDoList", { keyPath: "taskTitle" });

    // define what data items the objectStore will contain

    objectStore.createIndex("hours", "hours", { unique: false });
    objectStore.createIndex("minutes", "minutes", { unique: false });
    objectStore.createIndex("day", "day", { unique: false });
    objectStore.createIndex("month", "month", { unique: false });
    objectStore.createIndex("year", "year", { unique: false });

    objectStore.createIndex("notified", "notified", { unique: false });

    note.innerHTML += '&lt;li&gt;Object store created.&lt;/li&gt;';
  };</pre>

<p>This next line opens up a transaction on the Database, then opens an object store that we can then manipulate the data inside of.</p>

<pre class="brush: js">    var objectStore = db.transaction('toDoList').objectStore('toDoList'); </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-IDBDatabase', 'IDBDatabase')}}</td>
   <td>{{Spec2('IndexedDB')}}</td>
   <td>Initial version</td>
  </tr>
  <tr>
   <td>{{SpecName("IndexedDB 2", "#database-interface", "IDBDatabase")}}</td>
   <td>{{Spec2("IndexedDB 2")}}</td>
   <td> </td>
  </tr>
 </tbody>
</table>

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

{{Compat("api.IDBDatabase")}}

<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="http://mdn.github.io/to-do-notifications/">view example live</a>.)</li>
</ul>

<p> </p>