1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
---
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 += '<li>Error loading database.</li>';
};
DBOpenRequest.onsuccess = function(event) {
note.innerHTML += '<li>Database initialised.</li>';
// 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 += '<li>Error loading database.</li>';
};
// 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 += '<li>Object store created.</li>';
};</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>
|
