index.bs

<link rel="icon" href="logo-db.png">
<pre class=metadata>
Title: Indexed Database API 2.0
Shortname: IndexedDB
Abstract: This document defines APIs for a database of records holding
    simple values and hierarchical objects. Each record consists of a key
    and some value. Moreover, the database maintains indexes over records
    it stores. An application developer directly uses an API to locate
    records either by their key or by using an index. A query language can
    be layered on this API. An indexed database can be implemented using a
    persistent B-tree data structure.
Status: ED
Previous Version: https://www.w3.org/TR/IndexedDB/
ED: https://w3c.github.io/IndexedDB/
Level: 2
Editor: Ali Alabbas, alia@microsoft.com
Editor: Joshua Bell, jsbell@google.com
Group: webplatform
Test Suite: https://github.com/w3c/web-platform-tests/tree/master/IndexedDB
</pre>

<pre class=link-defaults>
spec:html; type:dfn; for:/; text:browsing context
spec:html; type:dfn; for:/; text:event loop
spec:html; type:dfn; for:/; text:origin
spec:html; type:dfn; for:/; text:task queue
</pre>

<pre class=anchors>
spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/
    urlPrefix: dom.html
        type: interface
            text: Document; url: document
    urlPrefix: workers.html
        type: dfn
            text: worker; url: worker
    urlPrefix: infrastructure.html
        type: dfn
            text: strictly splitting the string; url: strictly-split-a-string
            text: structured clone; url: structuredclone
            text: structured clone algorithm; url: safe-passing-of-structured-data
spec: ecma262; urlPrefix: https://tc39.github.io/ecma262/
    type: dfn
        url: sec-algorithm-conventions
            text: !
            text: ?
        text: abrupt completion; url: sec-completion-record-specification-type
        text: ReturnIfAbrupt; url: sec-returnifabrupt
        text: IdentifierName; url: prod-IdentifierName
        text: Type; url: sec-ecmascript-data-types-and-values
        text: HasOwnProperty; url: sec-hasownproperty
        text: Get; url: sec-get-o-p
        text: CreateDataProperty; url: sec-createdataproperty
        text: ToLength; url: sec-tolength
        text: ToString; url: sec-tostring
        text: IsArray; url: sec-isarray
        text: String; url: sec-ecmascript-language-types-string-type
        text: Number; url: sec-ecmascript-language-types-number-type
        text: Date; url: sec-date-objects
        text: Object; url: sec-object-objects
        text: TypeError; url: sec-native-error-types-used-in-this-standard-typeerror
        text: Array; url: sec-array-objects
        text: ArrayBuffer; url: sec-arraybuffer-objects
        text: Uint8Array; url: sec-typedarray-objects
        text: Promise; url: sec-promise-objects
spec: webidl; urlPrefix: https://heycam.github.io/webidl/
    type: dfn
        text: sequence<DOMString>; url: idl-sequence
        text: sequence<any>; url: idl-sequence
        text: octet; url: idl-octet
        text: getting a copy of the bytes held by a buffer source; url: dfn-get-buffer-source-copy
        text: create exception; url: dfn-create-exception
</pre>

<style>
table.props {
  border-collapse: collapse;
  border-style: hidden hidden none hidden;
}
table.props thead, table.props tbody {
  border-bottom: solid;
}
table.props td, table.props th {
  border-bottom: solid thin;
  border-left: solid;
  border-right: solid;
  padding: 0.5em;
  text-align: left;
  vertical-align: top;
}

dl.domintro dt {
    font-family: Menlo, Consolas, "DejaVu Sans Mono", Monaco, monospace;

    padding-top: 0.5em;
    padding-bottom: 1em;
}
dl.domintro dt a {
    color: inherit; border-bottom-style: none;
}
dl.domintro dt code {
    font-size: inherit;
}
</style>

This is the Second Edition of Indexed Database API. The
<a href="https://www.w3.org/TR/IndexedDB/">First Edition</a>
became a W3C Recommendation on 8 January 2015.


<!-- ============================================================ -->
<h2 id=introduction>Introduction</h2>
<!-- ============================================================ -->

User agents need to store large numbers of objects locally in order to
satisfy off-line data requirements of Web applications. [[WEBSTORAGE]]
is useful for storing pairs of keys and their corresponding values.
However, it does not provide in-order retrieval of keys, efficient
searching over values, or storage of duplicate values for a key.

This specification provides a concrete API to perform advanced
key-value data management that is at the heart of most sophisticated
query processors. It does so by using transactional databases to store
keys and their corresponding values (one or more per key), and
providing a means of traversing keys in a deterministic order. This is
often implemented through the use of persistent B-tree data structures
that are considered efficient for insertion and deletion as well as
in-order traversal of very large numbers of data records.


<aside class=example>
In the following example, the API is used to access a "library"
database that holds books stored by their "isbn" attribute.
Additionally, an index is maintained on the "title" attribute of the
objects stored in the object store. This index can be used to look up
books by title, and enforces a uniqueness constraint. Another index is
maintained on the "author" attribute of the objects, and can be used
to look up books by author.

A connection to the database is opened. If the "library" database did
not already exist, it is created and an event handler creates the
object store and indexes. Finally, the opened connection is saved for
use in subsequent examples.

<pre class=lang-javascript>
var request = indexedDB.open("library");

request.onupgradeneeded = function() {
  // The database did not previously exist, so create object stores and indexes.
  var db = request.result;
  var store = db.createObjectStore("books", {keyPath: "isbn"});
  var titleIndex = store.createIndex("by_title", "title", {unique: true});
  var authorIndex = store.createIndex("by_author", "author");

  // Populate with initial data.
  store.put({title: "Quarry Memories", author: "Fred", isbn: 123456});
  store.put({title: "Water Buffaloes", author: "Fred", isbn: 234567});
  store.put({title: "Bedrock Nights", author: "Barney", isbn: 345678});
};

request.onsuccess = function() {
  db = request.result;
};
</pre>

The following example populates the database using a transaction.

<pre class=lang-javascript>
var tx = db.transaction("books", "readwrite");
var store = tx.objectStore("books");

store.put({title: "Quarry Memories", author: "Fred", isbn: 123456});
store.put({title: "Water Buffaloes", author: "Fred", isbn: 234567});
store.put({title: "Bedrock Nights", author: "Barney", isbn: 345678});

tx.oncomplete = function() {
  // All requests have succeeded and the transaction has committed.
};
</pre>

The following example looks up a single book in the database by title
using an index.

<pre class=lang-javascript>
var tx = db.transaction("books", "readonly");
var store = tx.objectStore("books");
var index = store.index("by_title");

var request = index.get("Bedrock Nights");
request.onsuccess = function() {
  var matching = request.result;
  if (matching !== undefined) {
    // A match was found.
    report(matching.isbn, matching.title, matching.author);
  } else {
    // No match was found.
    report(null);
  }
};
</pre>

The following example looks up all books in the database by author
using an index and a cursor.

<pre class=lang-javascript>
var tx = db.transaction("books", "readonly");
var store = tx.objectStore("books");
var index = store.index("by_author");

var request = index.openCursor(IDBKeyRange.only("Fred"));
request.onsuccess = function() {
  var cursor = request.result;
  if (cursor) {
    // Called for each matching record.
    report(cursor.value.isbn, cursor.value.title, cursor.value.author);
    cursor.continue();
  } else {
    // No more matching records.
    report(null);
  }
};
</pre>

The following example shows how errors could be handled when a request
fails.

<pre class=lang-javascript>
var tx = db.transaction("books", "readwrite");
var store = tx.objectStore("books");
var request = store.put({title: "Water Buffaloes", author: "Slate", isbn: 987654});
request.onerror = function() {
  // The uniqueness constraint of the "by_title" index failed.
  report(request.error);
  // Could call request.preventDefault() to prevent the transaction from aborting.
};
tx.onabort = function() {
  // Otherwise the transaction will automatically abort due the failed request.
  report(tx.error);
};
</pre>

The database connection may be closed when it is no longer needed.

<pre class=lang-javascript>
db.close();
</pre>

In the future, the database may have grown to contain other object
stores and indexes. The following example shows one way to handle
migrating from an older version of the database.

<pre class=lang-javascript>
var request = indexedDB.open("library", 3); // Request version 3.

request.onupgradeneeded = function(event) {
  var db = request.result;
  if (event.oldVersion &lt; 1) {
    // Version 1 is the first version of the database.
    var store = db.createObjectStore("books", {keyPath: "isbn"});
    var titleIndex = store.createIndex("by_title", "title", {unique: true});
    var authorIndex = store.createIndex("by_author", "author");
  }
  if (event.oldVersion &lt; 2) {
    // Version 2 introduces a new index of books by year.
    var bookStore = request.transaction.objectStore("books");
    var yearIndex = bookStore.createIndex("by_year", "year");
  }
  if (event.oldVersion &lt; 3) {
    // Version 3 introduces a new object store for magazines with two indexes.
    var magazines = db.createObjectStore("magazines");
    var publisherIndex = magazines.createIndex("by_publisher", "publisher");
    var frequencyIndex = magazines.createIndex("by_frequency", "frequency");
  }
};

request.onsuccess = function() {
  db = request.result; // db.version will be 3.
};
</pre>
</aside>

<aside class=example id=handling-versionchange>
A single database can be used by multiple clients (pages and workers)
simultaneously - transactions ensure they don't clash while reading and writing.
However, if a new client wants to upgrade the database (via the "upgradeneeded"
event), it cannot do so until all other clients close their connection to the
current version of the database.

To avoid blocking a new client from upgrading, clients should listen for the
"versionchange" event. This fires when another client is wanting to upgrade the
database. To allow this to continue, react to the "versionchange" event by doing
something that ultimately closes this client's connection to the database.

One way of doing this is to reload the page:

<pre class=lang-javascript>
db.onversionchange = function() {
  // First, save any unsaved data:
  saveUnsavedData().then(function() {
    // If the document isn't being actively used, it may be appropriate to reload
    // the page without the user's interaction.
    if (!document.hasFocus()) {
      location.reload();
      // Reloading will close the database, and also reload with the new JavaScript
      // and database definitions.
    } else {
      // If the document has focus, it may be too disruptive to reload the page.
      // Maybe ask the user to do it manually:
      displayMessage("Please reload this page for the latest version.");
    }
  });
};

function saveUnsavedData() {
  // How you do this depends on your app.
}

function displayMessage() {
  // Show a non-modal message to the user.
}
</pre>

Another way is to call the database's close method. However, you need to make
sure your app is aware of this, as subsiquent attempts to access the database
will fail.

<pre class=lang-javascript>
db.onversionchange = function() {
  saveUnsavedData().then(function() {
    db.close();
    stopUsingTheDatabase();
  });
};

function stopUsingTheDatabase() {
  // Put the app into a state where it no longer uses the database.
}
</pre>

The new client (the one attempting the upgrade) can use the "blocked" event to
detect if other clients are preventing the upgrade from happening. The "blocked"
event fires if other clients still hold a connection to the database after their
"versionchange" events have fired.

<pre class=lang-javascript>
var request = indexedDB.open("library", 4); // Request version 4.
var blockedTimeout;

request.onblocked = function() {
  // Give the other clients time to save data asynchronously.
  blockedTimeout = setTimeout(function() {
    displayMessage("Upgrade blocked - Please close other tabs displaying this site.");
  }, 1000);
};

request.onupgradeneeded = function(event) {
  clearTimeout(blockedTimeout);
  hideMessage();
  // ...
};

function hideMessage() {
  // Hide a previously displayed message.
}
</pre>

The user will only see the above message if another client fails to disconnect
from the database. Ideally the user will never see this.
</aside>

<!-- ============================================================ -->
<h2 id=constructs>Constructs</h2>
<!-- ============================================================ -->

A <dfn>sorted list</dfn> is a {{DOMStringList}} containing strings
sorted in ascending order by code unit.


<!-- ============================================================ -->
<h3 id=database-construct>Database</h4>
<!-- ============================================================ -->

A database's [=origin=] is the same as the [=origin=] of the
[=document=] or [=worker=]. Each [=origin=] has an associated
set of databases.

<aside class=note>
  The database origin is not affected by changes to
  the {{Document}}'s {{Document/domain}}.
</aside>

Each [=origin=] has an associated set of [=databases=]. A
<dfn>database</dfn> has zero or more [=/object stores=] which
hold the data stored in the database.

<div dfn-for=database>

A [=database=] has a <dfn>name</dfn> which identifies it within a
specific [=origin=]. The name can be any string value, including
the empty string, and stays constant for the lifetime of the database.
Database names are always compared in a case-sensitive manner, as
opaque sequences of 16-bit code units. Implementations must support
all names.

<aside class=note>
  If an implementation uses a storage mechanism which can't handle
  arbitrary database names, the implementation must use an escaping
  mechanism or something similar to map the provided name to a name
  that it can handle.
</aside>

A [=database=] has a <dfn>version</dfn>. When a database is first
created, its [=database/version=] is 0 (zero).

<aside class=note>
  Each [=database=] has one version at a time; a [=database=] can't
  exist in multiple versions at once. The only way to change the
  version is using an [=upgrade transaction=].
</aside>

</div>

<!-- ============================================================ -->
<h4 id=database-connection>Database Connection</h4>
<!-- ============================================================ -->

Script does not interact with [=databases=] directly. Instead,
script has indirect access via a <dfn lt="connection|connected">connection</dfn>.
A [=/connection=] object can be used to manipulate the objects of
that [=database=]. It is also the only way to obtain a
[=/transaction=] for that [=database=].

The act of opening a [=database=] creates a [=/connection=].
There may be multiple [=/connections=] to a given [=database=] at
any given time.

<div dfn-for=connection>

A [=/connection=] has a <dfn>version</dfn>, which is set when
the [=/connection=] is created. It remains constant for the
lifetime of the [=/connection=] unless an <a data-lt="steps
for aborting an upgrade transaction">upgrade is aborted</a>, in which
case it is set to the previous version of the [=database=]. Once
the [=/connection=] is closed the
[=connection/version=] does not change.

Each connection has a <dfn>close pending flag</dfn> which is initially
unset.

When a [=/connection=] is initially created it is in <dfn>opened</dfn>
state. The connection can be <dfn>closed</dfn> through several means.
If the execution context where the [=/connection=] was created is
destroyed (for example due to the user navigating away from that
page), the connection is closed. The connection can also be closed
explicitly using the [=steps for closing a database connection=]. When
the connection is closed the [=close pending flag=] is always set if
it hasn't already been.

A [=/connection=] may be closed by a user agent in exceptional
circumstances, for example due to loss of access to the file system, a
permission change, or clearing of the origin's storage. If this occurs
the user agent must run the [=steps for closing a database
connection=] with the [=/connection=] and with the |forced flag| set.

<aside class=advisement>
  &#x1F6A7;
  This behavior is new in this edition.
  It is supported in Chrome 31 and Firefox 50.
  &#x1F6A7;
</aside>

A [=/connection=] has an <dfn>object store set</dfn>, which is
initialized to the set of [=/object stores=] in the associated
[=database=] when the [=/connection=] is created. The contents of the
set will remain constant except when an [=upgrade transaction=] is
running.

A [=/connection=]'s [=get the parent=] algorithm returns
null.

</div>


<!-- ============================================================ -->
<h3 id=object-store-construct>Object Store</h3>
<!-- ============================================================ -->

An <dfn>object store</dfn> is the primary storage mechanism for
storing data in a [=database=].

<div dfn-for=object-store>

Each database has a set of [=/object stores=]. The set of [=/object
stores=] can be changed, but only using an [=upgrade transaction=],
i.e. in response to an <code>[=upgradeneeded=]</code> event. When a
new database is created it doesn't contain any [=/object stores=].

An [=/object store=] has a <dfn>list of records</dfn> which hold the
data stored in the object store. Each <dfn>record</dfn> consists of a
[=/key=] and a [=/value=]. The list is sorted according to key in
ascending order. There can never be multiple records in a given object
store with the same key.

An [=/object store=] has a <dfn>name</dfn>. The name can be any string
value, including the empty string. At any one time, the name is unique
within the [=database=] to which it belongs. Object store names are
always compared in a case-sensitive manner, as opaque sequences of
16-bit code units.

An [=/object store=] optionally has a <dfn>key path</dfn>. If the
object store has a key path it is said to use <dfn>in-line keys</dfn>.
Otherwise it is said to use <dfn>out-of-line keys</dfn>.

An [=/object store=] optionally has a [=key generator=].

An object store can derive a [=/key=] for a [=object-store/record=] from
one of three sources:

1. A [=key generator=]. A key generator generates a monotonically
    increasing numbers every time a key is needed.

2. Keys can be derived via a [=object-store/key path=].

3. Keys can also be explicitly specified when a [=/value=] is stored
    in the object store.

</div>

<!-- ============================================================ -->
<h4 id=object-store-handle-construct>Object Store Handle</h4>
<!-- ============================================================ -->

Script does not interact with [=/object stores=] directly. Instead,
within a [=/transaction=], script has indirect access via an
<dfn>object store handle</dfn>.

<div dfn-for=object-store-handle>

An [=/object store handle=] has an associated <dfn>object store</dfn>
and an associated <dfn>transaction</dfn>. Multiple handles may be
associated with the same [=/object store=] in different
[=/transactions=], but there must be only one [=/object store handle=]
associated with a particular [=/object store=] within a
[=/transaction=].

An [=/object store handle=] has an <dfn>index set</dfn>, which is
initialized to the set of [=/indexes=] that reference the associated
[=object-store-handle/object store=] when the [=/object store handle=]
is created. The contents of the set will remain constant except when
an [=upgrade transaction=] is running.

An [=/object store handle=] has a <dfn>name</dfn>, which is
initialized to the [=object-store/name=] of the associated
[=object-store-handle/object store=] when the [=/object store handle=]
is created. The name will remain constant except when an [=upgrade
transaction=] is running.

</div>

<!-- ============================================================ -->
<h3 id=value-construct>Values</h3>
<!-- ============================================================ -->

Each record is associated with a <dfn>value</dfn>. User agents must
support any ECMAScript [[!ECMA-262]] value supported by the
[=structured clone algorithm=] [[!HTML]]. This includes simple types
such as [=String=] primitive values and [=Date=] objects as well as
[=Object=] and [=Array=] instances, {{File}} objects, {{Blob}}
objects, {{ImageData}} objects, and so on. Record [=/values=] are
stored and retrieved by value rather than by reference; later changes
to a value have no effect on the record stored in the database.


<!-- ============================================================ -->
<h3 id=key-construct>Keys</h3>
<!-- ============================================================ -->

In order to efficiently retrieve [=object-store/records=] stored in an indexed
database, each [=object-store/record=] is organized according to its
<dfn>key</dfn>.

<div dfn-for=key>

A [=/key=] has an associated <dfn>type</dfn> which is one of:
<i>number</i>,
<i>date</i>,
<i>string</i>,
<i>binary</i>,
or
<i>array</i>.

<aside class=advisement>
  &#x1F6A7;
  <i>Binary</i> keys are new in this edition.
  They will be supported in Firefox 51.
  &#x1F6A7;
</aside>

A [=/key=] also has an associated <dfn>value</dfn>, which will
be either:
an {{unrestricted double}} if type is <i>number</i> or <i>date</i>,
a {{DOMString}} if type is <i>string</i>,
a list of [=octets=] if type is <i>binary</i>,
or a list of other [=/keys=] if type is <i>array</i>.

</div>

An ECMAScript [[!ECMA-262]] value can be converted to a [=/key=] by
following the steps to [=convert a value to a key=].

<aside class=note>
  The following ECMAScript types are valid keys:

  * [=Number=] primitive values, except NaN. This includes Infinity
      and -Infinity.
  * [=Date=] objects, except where the \[[DateValue]]
      internal slot is NaN.
  * [=String=] primitive values.
  * [=ArrayBuffer=] objects (or views on buffers such as
      [=Uint8Array=]).
  * [=Array=] objects, where every item is defined, is itself a valid
      key, and does not directly or indirectly contain itself. This
      includes empty arrays. Arrays may contain other arrays.

  Attempting to convert other ECMAScript values to a [=/key=]
  will fail.
</aside>

An <dfn>array key</dfn> is a [=/key=] with [=key/type=] <i>array</i>.
The <dfn>subkeys</dfn> of an [=array key=] are the members of the
[=array key=]'s [=key/value=] list.

To <dfn>compare two keys</dfn> |a| and |b|, run these steps:

<div class=algorithm>

1. Let |ta| be the [=key/type=] of |a|.

2. Let |tb| be the [=key/type=] of |b|.

3. If |ta| is <i>array</i> and |tb| is <i>binary</i>, <i>string</i>,
    <i>date</i> or <i>number</i>, return 1.

4. If |tb| is <i>array</i> and |ta| is <i>binary</i>, <i>string</i>,
    <i>date</i> or <i>number</i>, return -1.

5. If |ta| is <i>binary</i> and |tb| is <i>string</i>, <i>date</i> or
    <i>number</i>, return 1.

6. If |tb| is <i>binary</i> and |ta| is <i>string</i>, <i>date</i> or
    <i>number</i>, return -1.

7. If |ta| is <i>string</i> and |tb| is <i>date</i> or <i>number</i>,
    return 1.
8. If |tb| is <i>string</i> and |ta| is <i>date</i> or <i>number</i>,
    return -1.

9. If |ta| is <i>date</i> and |tb| is <i>number</i>, return 1.

10. If |tb| is <i>date</i> and |ta| is <i>number</i>, return -1.

11. Assert: |ta| and |tb| are equal.

12. Let |va| be the [=key/value=] of |a|.

13. Let |vb| be the [=key/value=] of |b|.

14. Switch on |ta|:

    <dl class=switch>
      <dt><i>number</i></dt>
      <dt><i>date</i></dt>
      <dd>
        1. If |va| is greater than |vb|, then return 1.
        2. If |va| is less than |vb|, then return -1.
        3. Return 0.
      </dd>

      <dt><i>string</i></dt>
      <dd>
        1. Let |length| be the lesser of |va|'s length and |vb|'s length.
        2. Let |i| be 0.
        3. While |i| is less than |length|, run these substeps:
            1. Let |u| be the code unit of |va| at index |i|.
            2. Let |v| be the code unit of |vb| at index |i|.
            3. If |u| is greater than |v| then return 1.
            4. If |u| is less than |v| then return -1.
            5. Increase |i| by 1.
        4. If |va|'s length is greater than |vb|'s length, then return 1.
        5. If |va|'s length is less than |vb|'s length, then return -1.
        6. Return 0.
      </dd>

      <dt><i>binary</i></dt>
      <dd>
        1. Let |length| be the lesser of |va|'s length and |vb|'s length.
        2. Let |i| be 0.
        3. While |i| is less than |length|, run these substeps:

            1. Let |u| be the [=octet=] in |va| at index |i|.
            2. Let |v| be the [=octet=] in |vb| at index |i|.
            3. If |u| is greater than |v| then return 1.
            4. If |u| is less than |v| then return -1.
            5. Increase |i| by 1.

        4. If |va|'s length is greater than |vb|'s length, then return 1.
        5. If |va|'s length is less than |vb|'s length, then return -1.
        6. Return 0.
      </dd>

      <dt><i>array</i></dt>
      <dd>
        1. Let |length| be the lesser of |va|'s length and |vb|'s length.
        2. Let |i| be 0.
        3. While |i| is less than |length|, run these substeps:

            1. Let |u| be the [=/key=] in |va| at index |i|.
            2. Let |v| be the [=/key=] in |vb| at index |i|.
            3. Let |c| be the result of recursively running the steps to [=compare two keys=] with |u| and |v|.
            4. If |c| is not 0, return |c|.
            5. Increase |i| by 1.

        4. If |va|'s length is greater than |vb|'s length, then return 1.
        5. If |va|'s length is less than |vb|'s length, then return -1.
        6. Return 0.
      </dd>
    </dl>

</div>

The [=/key=] |a| is <dfn>greater than</dfn> the [=/key=] |b| if the
result of running the steps to [=compare two keys=] with |a| and |b|
is 1.

The [=/key=] |a| is <dfn>less than</dfn> the [=/key=] |b| if the
result of running the steps to [=compare two keys=] with |a| and |b|
is -1.

The [=/key=] |a| is <dfn>equal to</dfn> the [=/key=] |b| if the result
of running the steps to [=compare two keys=] with |a| and |b| is 0.

<aside class=note>
  As a result of the above rules, negative infinity is the lowest
  possible value for a [=/key=].
  <i>Number</i> keys are less than <i>date</i> keys.
  <i>Date</i> keys are less than <i>string</i> keys.
  <i>String</i> keys are less than <i>binary</i> keys.
  <i>Binary</i> keys are less than <i>array</i> keys.
  There is no highest possible [=/key=] value.
  This is because an array of any candidate highest [=/key=]
  followed by another [=/key=] is even higher.
</aside>

<aside class=note>
  Members of <i>binary</i> keys are compared as unsigned octet values
  (in the range [0, 255]) rather than signed bytes (in the range
  [-128, 127]).
</aside>


<!-- ============================================================ -->
<h3 id=key-path-construct>Key Path</h3>
<!-- ============================================================ -->

A <dfn>key path</dfn> is a {{DOMString}} or
[=sequence&lt;DOMString&gt;=] that defines how to extract a [=/key=]
from a [=/value=]. A <dfn>valid key path</dfn> is one of:

* An empty {{DOMString}}.
* An <dfn>identifier</dfn>, which is a {{DOMString}} matching the
    [=IdentifierName=] production from the ECMAScript Language
    Specification [[!ECMA-262]].
* A {{DOMString}} consisting of two or more [=identifiers=] separated
    by periods (ASCII character code 46, U+002E FULL STOP).
* A non-empty [=sequence&lt;DOMString&gt;=] containing only strings
    conforming to the above requirements.

<aside class=note>
  Spaces are not allowed within a key path.
</aside>

[=/Key path=] values can only be accessed from properties explicitly
copied by the [=structured clone algorithm=], as well as the
following type-specific properties:

<table class=props>
  <tr><th>Type</th><th>Properties</th></tr>
  <tr><td>{{Blob}}</td><td>{{Blob/size}}, {{Blob/type}}</td></tr>
  <tr><td>{{File}}</td><td>{{File/name}}, {{File/lastModified}}, <code>lastModifiedDate</code></td></tr>
  <tr><td>[=Array=]</td><td><code>length</code></td></tr>
  <tr><td>[=String=]</td><td><code>length</code></td></tr>
</table>


<!-- ============================================================ -->
<h3 id=index-construct>Index</h3>
<!-- ============================================================ -->

It is sometimes useful to retrieve [=object-store/records=] in an
[=/object store=] through other means than their
[=/key=]. An <dfn id=index-concept>index</dfn> allows looking up
[=object-store/records=] in an [=/object store=] using properties of the
[=/values=] in the [=/object stores=] [=object-store/records=].

<div dfn-for=index>

An index is a specialized persistent key-value storage and has a <dfn
lt="referenced|references">referenced</dfn> [=/object store=]. The
index has a <dfn>list of records</dfn> which hold the data stored in
the index. The <dfn>records</dfn> in an index are automatically populated
whenever records in the [=referenced=] object store are inserted,
updated or deleted. There can be several [=/indexes=] referencing the
same [=/object store=], in which changes to the object store cause all
such indexes to get updated.

The <dfn>values</dfn> in the index's [=index/records=] are always values of [=/keys=]
in the index's [=referenced=] object store. The <dfn>keys</dfn> are derived from
the referenced object store's [=/values=] using a <dfn>key path</dfn>.
If a given [=object-store/record=] with key |X| in the object store referenced by
the index has the value |A|, and <a data-lt="extract a key from a
value using a key path">evaluating</a> the index's [=index/key path=]
on |A| yields the result |Y|, then the index will contain a record
with key |Y| and value |X|.

<aside class=example>
  For example, if an index's [=referenced=] object store contains a
  record with the key <code>123</code> and the value <code>{ first:
  "Alice", last: "Smith" }</code>, and the index's [=index/key path=]
  is "<code>first</code>" then the index would contain a record with
  the key "<code>Alice</code>" and the value <code>123</code>.
</aside>

Records in an index are said to have a <dfn>referenced value</dfn>.
This is the value of the record in the index's referenced object store
which has a key equal to the index's record's value. So in the example
above, the record in the index whose key is |Y| and value is |X| has a
[=referenced value=] of |A|.

<aside class=example>
  In the preceding example, the record in the index with key
  "<code>Alice</code>" and value <code>123</code> would have a
  [=referenced value=] of <code>{ first: "Alice", last: "Smith"
  }</code>.
</aside>

<aside class=note>
  Each record in an index references one and only one record in the
  index's [=referenced=] object store. However there can be multiple
  records in an index which reference the same record in the object
  store. And there can also be no records in an index which reference
  a given record in an object store.
</aside>

The [=object-store/records=] in an index are always sorted according to the
[=object-store/record=]'s key. However unlike object stores, a given index can
contain multiple records with the same key. Such records are
additionally sorted according to the [=/index=]'s [=object-store/record=]'s value
(meaning the key of the record in the referenced [=/object store=]).

An [=/index=] has a <dfn>name</dfn>. The name can be any
string value, including the empty string. At any one time, the name is
unique within index's [=referenced=] [=/object store=].
Index names are always compared in a case-sensitive manner, as opaque
sequences of 16-bit code units.

An [=/index=] has a <dfn>unique flag</dfn>. When this flag is
set, the index enforces that no two [=object-store/records=] in the index has
the same key. If a [=object-store/record=] in the index's referenced object
store is attempted to be inserted or modified such that evaluating the
index's key path on the records new value yields a result which
already exists in the index, then the attempted modification to the
object store fails.

An [=/index=] has a <dfn>multiEntry flag</dfn>. This flag affects how
the index behaves when the result of evaluating the index's
[=index/key path=] yields an [=array key=]. If the [=multiEntry flag=]
is unset, then a single [=object-store/record=] whose [=/key=] is an [=array key=]
is added to the index. If the [=multiEntry flag=] is true, then the
one [=object-store/record=] is added to the index for each of the [=subkeys=].

</div>

<!-- ============================================================ -->
<h4 id=index-handle-construct>Index Handle</h4>
<!-- ============================================================ -->

Script does not interact with [=/indexes=] directly. Instead, within
a [=/transaction=], script has indirect access via an <dfn>index
handle</dfn>.

<div dfn-for=index-handle>

An [=index handle=] has an associated <dfn>index</dfn> and an
associated <dfn>object store handle</dfn>. The <dfn>transaction</dfn>
of an [=index handle=] is the [=object-store-handle/transaction=] of
its associated [=/object store handle=]. Multiple handles may be
associated with the same [=/index=] in different [=/transactions=],
but there must be only one [=index handle=] associated with a
particular [=/index=] within a [=/transaction=].

An [=index handle=] has a <dfn>name</dfn>, which is initialized to the
[=index/name=] of the associated [=index-handle/index=] when the
[=index handle=] is created. The name will remain constant except when
an [=upgrade transaction=] is running.

</div>

<!-- ============================================================ -->
<h3 id=transaction-construct>Transactions</h3>
<!-- ============================================================ -->

A <dfn id=transaction-concept>Transaction</dfn> is used to interact
with the data in a [=database=]. Whenever data is read or written
to the database it is done by using a [=/transaction=].

<div dfn-for=transaction>

[=/Transactions=] offer some protection from application and system
failures. A [=/transaction=] may be used to store multiple data
records or to conditionally modify certain data records. A
[=/transaction=] represents an atomic and durable set of data access
and data mutation operations.

All transactions are created through a [=/connection=], which is the
transaction's <dfn>connection</dfn>.

A [=/transaction=] has a <dfn>scope</dfn> that determines the
[=/object stores=] with which the transaction may interact. A
transaction's scope remains fixed for the lifetime of that
transaction.

A [=/transaction=] has a <dfn>mode</dfn> that determines which types
of interactions can be performed upon that transaction. The [=transaction/mode=]
is set when the transaction is created and remains fixed for the life
of the transaction. A [=/transaction=]'s [=transaction/mode=] is one of the
following:

<dl>
  <dt>{{"readonly"}}</dt>
  <dd>
    The transaction is only allowed to read data. No modifications can
    be done by this type of transaction. This has the advantage that
    several [=read-only transactions=] can run at the same time even
    if their [=transaction/scopes=] are overlapping, i.e. if they are using the
    same object stores. This type of transaction can be created any
    time once a database has been opened.
  </dd>

  <dt>{{"readwrite"}}</dt>
  <dd>
    The transaction is allowed to read, modify and delete data from
    existing object stores. However object stores and indexes can't be
    added or removed. Multiple {{"readwrite"}} transactions
    can't run at the same time if their [=transaction/scopes=] are overlapping
    since that would mean that they can modify each other's data in
    the middle of the transaction. This type of transaction can be
    created any time once a database has been opened.
  </dd>

  <dt>{{"versionchange"}}</dt>
  <dd>
    The transaction is allowed to read, modify and delete data from
    existing object stores, and can also create and remove object
    stores and indexes. It is the only type of transaction that can do
    so. This type of transaction can't be manually created, but
    instead is created automatically when an
    <code>[=upgradeneeded=]</code> event is fired.
  </dd>
</dl>

A [=/transaction=] has an <dfn>active flag</dfn>, which determines
if new [=requests=] can be made against the transaction. A
transaction is said to be <dfn>active</dfn> if its [=transaction/active flag=]
is set.

A [=/transaction=] has a <dfn>request list</dfn> of [=requests=]
which have been made against the transaction.

A [=/transaction=] has a <dfn>error</dfn> which is set if the
[=/transaction=] is [=transaction/aborted=].

A [=/transaction=]'s [=get the parent=] algorithm returns the
transaction's [=transaction/connection=].

A <dfn>read-only transaction</dfn> is
a [=/transaction=] with [=transaction/mode=] {{"readonly"}}.

A <dfn>read/write transaction</dfn>
is a [=/transaction=] with [=transaction/mode=] {{"readwrite"}}.


<!-- ============================================================ -->
<h4 id=transaction-lifetime-concept>Transaction Lifetime</h4>
<!-- ============================================================ -->

Transactions are expected to be short lived. This is encouraged by the
<a for=transaction lt=commit>automatic committing</a> functionality
described below.

<aside class=note>
  Authors can still cause transactions to run for a long time; however,
  this usage pattern is not generally recommended as it can lead to a
  bad user experience.
</aside>

The <dfn>lifetime</dfn> of a
[=/transaction=] is as follows:

1. A transaction is <dfn>created</dfn> with a [=transaction/scope=] and a [=transaction/mode=].
    When a transaction is created its [=transaction/active flag=] is initially set.

2. The implementation must allow [=requests=] to be [=request/placed=]
    against the transaction whenever the [=transaction/active flag=] is set. This
    is the case even if the transaction has not yet been [=transaction/started=].
    Until the transaction is [=transaction/started=] the implementation must not
    execute these requests; however, the implementation must keep
    track of the [=requests=] and their order. Requests may be placed
    against a transaction only while that transaction is [=transaction/active=].
    If an attempt is made to place a request against a transaction
    when that transaction is not [=transaction/active=], the implementation must
    reject the attempt by throwing a "{{TransactionInactiveError}}" {{DOMException}}.

3. Once an implementation is able to enforce the constraints defined
    for the transaction [=transaction/scope=] and [=transaction/mode=], defined below, the
    implementation must [=queue a task=] to <dfn
    lt="start|started">start</dfn> the transaction asynchronously.

4. Once the transaction has been [=transaction/started=] the implementation can
    start executing the [=requests=] placed against the transaction.
    Unless otherwise defined, requests must be executed in the order
    in which they were made against the transaction. Likewise, their
    results must be returned in the order the requests were placed
    against a specific transaction. There is no guarantee about the
    order that results from requests in different transactions are
    returned. Similarly, the transaction [=transaction/modes=] ensure that two
    requests placed against different transactions can execute in any
    order without affecting what resulting data is stored in the
    database.

5. A transaction can be <dfn lt="abort|aborting|aborted">aborted</dfn>
    at any time before it is [=transaction/finished=], even if the transaction
    isn't currently [=transaction/active=] or hasn't yet [=transaction/started=]. When a
    transaction is aborted the implementation must undo (roll back)
    any changes that were made to the [=database=] during that
    transaction. This includes both changes to the contents of
    [=/object stores=] as well as additions and removals of [=/object
    stores=] and [=/indexes=].

6. A transaction can fail for reasons not tied to a particular
    [=request=]. For example due to IO errors when committing the
    transaction, or due to running into a quota limit where the
    implementation can't tie exceeding the quota to a partcular
    request. In this case the implementation must run the [=steps for
    aborting a transaction=] using the transaction as |transaction|
    and the appropriate error type as |error|. For example if quota
    was exceeded then a "{{QuotaExceededError}}" {{DOMException}} should be used as
    |error|, and if an IO error happened, an "{{UnknownError}}" {{DOMException}} should be
    used as |error|.

7. When a transaction has been started and it can no longer become
    [=transaction/active=], the implementation must attempt to <dfn
    lt="commit|committing|committed">commit</dfn> it, as long as the
    transaction has not been [=transaction/aborted=]. This usually happens after
    all requests placed against the transaction have been executed and
    their returned results handled, and no new requests have been
    placed against the transaction. When a transaction is committed,
    the implementation must atomically write any changes to the
    [=database=] made by requests placed against the transaction. That
    is, either all of the changes must be written, or if an error
    occurs, such as a disk write error, the implementation must not
    write any of the changes to the database. If such an error occurs,
    the implementation must [=transaction/abort=] the transaction by following the
    [=steps for aborting a transaction=], otherwise it must
    [=transaction/commit=] the transaction by following the [=steps
    for committing a transaction=].

8. When a transaction is [=transaction/committed=] or [=transaction/aborted=], it
    is said to be <dfn lt="finish|finished">finished</dfn>. If a
    transaction can't be finished, for example due to the
    implementation crashing or the user taking some explicit action to
    cancel it, the implementation must [=transaction/abort=] the transaction.

The following constraints define when a [=/transaction=] can be
[=transaction/started=]:

* Any number of [=read-only transactions=] are allowed to run
    concurrently, even if the transaction's [=transaction/scope=] overlap and
    include the same [=/object stores=]. As long as a [=read-only
    transaction=] is running, the data that the implementation returns
    through [=requests=] created with that transaction must remain
    constant. That is, two requests to read the same piece of data
    must yield the same result both for the case when data is found
    and the result is that data, and for the case when data is not
    found and a lack of data is indicated.

    <aside class=note>
      There are a number of ways that an implementation can ensure
      this. The implementation could prevent any <a>read/write
      transaction</a>, whose scope overlaps the scope of the
      [=read-only transaction=], from starting until the
      [=read-only transaction=] finishes. Or the implementation
      could allow the [=read-only transaction=] to see a snapshot
      of the contents of the [=/object stores=] which is taken when
      the [=read-only transaction=] started.
    </aside>

* Similarly, implementations must ensure that a <a>read/write
    transaction</a> is only affected by changes to [=/object
    stores=] that are made using the transaction itself. For
    example, the implementation must ensure that another transaction
    does not modify the contents of [=/object stores=] in the
    <a>read/write transaction</a>'s [=transaction/scope=]. The implementation
    must also ensure that if the <a>read/write transaction</a>
    completes successfully, the changes written to [=/object
    stores=] using the transaction can be committed to the
    [=database=] without merge conflicts. An implementation must
    not abort a transaction due to merge conflicts.

* If multiple <a>read/write transactions</a> are attempting to access
    the same object store (i.e. if they have overlapping [=transaction/scope=]),
    the transaction that was [=transaction/created=] first must be the transaction
    which gets access to the object store first. Due to the
    requirements in the previous paragraph, this also means that it is
    the only transaction which has access to the object store until
    the transaction is [=transaction/finished=].

* Any transaction [=transaction/created=] after a <a>read/write transaction</a>
    must see the changes written by the <a>read/write transaction</a>.
    So if a <a>read/write transaction</a>, A, is created, and later
    another transaction B, is created, and the two transactions have
    overlapping [=transaction/scopes=], then B must see any changes made to any
    [=/object stores=] that are part of that overlapping [=transaction/scope=].
    Due to the requirements in the previous paragraph, this also means
    that the B transaction does not have access to any [=/object
    stores=] in that overlapping [=transaction/scope=] until the A transaction is
    [=transaction/finished=].

    <aside class=note>
      Generally speaking, the above requirements mean that any
      transaction which has an overlapping scope with a <a>read/write
      transaction</a> and which was created after that <a>read/write
      transaction</a>, can't run in parallel with that <a>read/write
      transaction</a>.
    </aside>

* User agents must ensure a reasonable level of fairness across
    transactions to prevent starvation. For example, if multiple
    [=read-only transactions=] are started one after another the
    implementation must not indefinitely prevent a pending
    <a>read/write transaction</a> from [=/starting=].

</div>

<!-- ============================================================ -->
<h4 id=upgrade-transaction-construct>Upgrade Transactions</h4>
<!-- ============================================================ -->

An <dfn>upgrade transaction</dfn> is a [=/transaction=] with [=transaction/mode=]
{{"versionchange"}}.

An [=upgrade transaction=] is automatically created when running
[=steps for running an upgrade transaction=] after a [=/connection=]
is opened to a [=database=] giving a greater [=database/version=] than
the current [=database/version=]. This [=/transaction=] will be active
inside the <code>[=upgradeneeded=]</code> event handler, allowing the
creation of new [=/object stores=] and [=/indexes=].

An [=upgrade transaction=] is never run concurrently with other
transactions. When a database is opened with a [=database/version=]
number higher than the current [=database/version=], a new [=upgrade
transaction=] is automatically created and made available through the
[=open request=] when the <code>[=upgradeneeded=]</code> event is
fired. The <code>[=upgradeneeded=]</code> event isn't fired, and thus
the [=upgrade transaction=] isn't started, until all other
[=/connections=] to the same [=database=] are closed. This ensures
that all other transactions are [=transaction/finished=].

As long as an [=upgrade transaction=] is running, attempts to open
more [=/connections=] to the same [=database=] are delayed, and
any attempts to use the same [=/connection=] to start additional
transactions will result in an exception being thrown. Thus [=upgrade
transactions=] not only ensure that no other transactions are
running concurrently, but also ensure that no other transactions are
queued against the same [=database=] as long as the transaction is
running.


<!-- ============================================================ -->
<h3 id=request-construct>Requests</h3>
<!-- ============================================================ -->

Each asynchronous operation on a [=database=] is done using a <dfn>request</dfn>. Every request represents one
operation.

<div dfn-for=request>

A [=request=] has a <dfn>done flag</dfn> which is initially unset.

A [=request=] has a <dfn>source</dfn> object.

A [=request=] has a <dfn>result</dfn> and an <dfn>error</dfn>, neither
of which are accessible until the [=request/done flag=] is set.

A [=request=] has a <dfn>transaction</dfn> which is initially null.
This will be set when a request is <dfn>placed</dfn> against a
[=/transaction=] using the [=steps for asynchronously executing a
request=].

When a request is made, a new [=request=] is returned with its [=request/done
flag=] unset. If a request completes successfully, the [=request/done flag=]
is set, the [=request/result=] is set to the result of the request,
and an event with type <code>success</code> is fired at the
[=request=].

If an error occurs while performing the operation, the [=request/done flag=]
is set, the [=request/error=] is set to the error, and an event with
type <code>error</code> is fired at the request.

A [=request=]'s [=get the parent=] algorithm returns the request's
[=request/transaction=].

<aside class=note>
  Requests are not typically re-used, but there are exceptions. When a
  [=cursor=] is iterated, the success of the iteration is reported
  on the same [=request=] object used to open the cursor. And when
  an [=upgrade transaction=] is necessary, the same [=open
  request=] is used for both the <code>[=upgradeneeded=]</code>
  event and final result of the open operation itself. In both cases,
  the request's [=request/done flag=] will be unset then set again, and the
  [=request/result=] may change.
</aside>

<!-- ============================================================ -->
<h4 id=open-requests>Open Requests</h4>
<!-- ============================================================ -->

An <dfn>open request</dfn> is a special type of [=request=] used
when opening a [=/connection=] or deleting a [=database=].
In addition to <code>success</code> and <code>error</code> events,
<dfn><code>blocked</code></dfn> and
<dfn><code>upgradeneeded</code></dfn> may be fired at an [=open
request=] to indicate progress.

The [=request/source=] of an [=open request=]
is always null.

The [=request/transaction=] of an [=open request=] is null
unless an <code>[=upgradeneeded=]</code> event has been fired.

An [=open request=]'s [=get the parent=] algorithm returns null.

[=Open requests=] are processed in a <dfn>connection queue</dfn>.
The queue contains all [=open requests=] associated with an
[=origin=] and a [=database/name=]. Requests added to the
[=connection queue=] processed in order and each request must run
to completion before the next request is processed. An open request
may be blocked on other [=/connections=], requiring those
connections to [=connection/close=] before the request can complete and allow
further requests to be processed.

<aside class=note>
  A [=connection queue=] is not a [=task queue=] associated with
  an [=event loop=], as the requests are processed outside any
  specific [=browsing context=]. The delivery of events to
  completed [=open request=] still goes through a [=task queue=]
  associated with the [=event loop=] of the context where the
  request was made.
</aside>

</div>

<!-- ============================================================ -->
<h3 id=range-construct>Key Range</h3>
<!-- ============================================================ -->

Records can be retrieved from [=/object stores=] and [=/indexes=]
using either [=/keys=] or [=key ranges=]. A <dfn>key range</dfn> is a
continuous interval over some data type used for keys.

A [=key range=] has an associated <dfn>lower bound</dfn> (null or a
[=/key=]).

A [=key range=] has an associated <dfn>upper bound</dfn> (null or a
[=/key=]).

A [=key range=] has an associated <dfn>lower open flag</dfn>.
Unless otherwise stated it is unset.

A [=key range=] has an associated <dfn>upper open flag</dfn>.
Unless otherwise stated it is unset.

A [=key range=] may have a [=lower bound=] [=equal to=] its
[=upper bound=]. A [=key range=] must not have a [=lower
bound=] [=greater than=] its [=upper bound=].

A [=key range=] <dfn>containing only</dfn> |key| has both
[=lower bound=] and [=upper bound=] equal to |key|.

A |key| is <dfn lt="in">in a key range</dfn> if both of the following
conditions are fulfilled:

* The [=lower bound=] is null, or it is [=less than=]
    |key|, or it is both [=equal to=] |key| and
    the [=lower open flag=] is unset.

* The [=upper bound=] is null, or it is [=greater than=]
    |key|, or it is both [=equal to=] |key| and
    the [=upper open flag=] is unset.

<aside class=note>

  * If the [=lower open flag=] of a [=key range=] is unset, the
    [=lower bound=] [=/key=] of the [=key range=] is included
    in the range itself.

  * If the [=lower open flag=] of a [=key range=] is set, the
    [=lower bound=] [=/key=] of the [=key range=] is excluded
    from the range itself.

  * If the [=upper open flag=] of a [=key range=] is unset, the
    [=upper bound=] [=/key=] of the [=key range=] is included
    in the range itself.

  * If the [=upper open flag=] of a [=key range=] is set, the
    [=upper bound=] [=/key=] of the [=key range=] is excluded
    from the range itself.

</aside>

An <dfn>unbounded key range</dfn> is a [=key range=] that has both
[=lower bound=] and [=upper bound=] equal to null. All
[=/keys=] are [=in=] an [=unbounded key
range=].

The steps to <dfn>convert a value to a key range</dfn> with
|value| and optional |null disallowed flag| are as
follows:

<div class=algorithm>

1. If |value| is a [=key range=], return |value|.

2. If |value| is undefined or is null, then [=throw=] a
    "{{DataError}}" {{DOMException}} if |null disallowed flag| is set, or return an
    [=unbounded key range=] otherwise.

3. Let |key| be the result of running the steps to [=convert
    a value to a key=] with |value|. Rethrow any exceptions.

4. If |key| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

5. Return a [=key range=] [=containing only=] |key|.

</div>

<!-- ============================================================ -->
<h3 id=cursor-construct>Cursor</h3>
<!-- ============================================================ -->

A <dfn>cursor</dfn> is used to iterate over a range of records in an
[=/index=] or an [=/object store=] in a specific direction.

<div dfn-for=cursor>

A [=cursor=] has a <dfn>transaction</dfn>, the [=/transaction=]
that was [=transaction/active=] when the cursor was created.

A [=cursor=] has a <dfn>range</dfn> of records in either an
[=/index=] or an [=/object store=].

A [=cursor=] has a <dfn>source</dfn> that indicates which [=/index=]
or an [=/object store=] is associated with the records over which
the [=cursor=] is iterating.

A [=cursor=] has a <dfn>direction</dfn> that determines whether it
moves in monotonically increasing or decreasing order of the
[=object-store/record=] keys when iterated, and if it skips duplicated values
when iterating indexes. The direction of a cursor also determines if
the cursor initial position is at the start of its
[=cursor/source=] or at its end. A cursor's
[=cursor/direction=] is one of the following:

<dl>
  <dt>{{"next"}}</dt>
  <dd>
    This direction causes the cursor to be opened at the start of the
    [=cursor/source=]. When iterated, the [=cursor=] should yield all
    records, including duplicates, in monotonically increasing order
    of keys.
  </dd>

  <dt>{{"nextunique"}}</dt>
  <dd>
    This direction causes the cursor to be opened at the start of the
    [=cursor/source=]. When iterated, the [=cursor=] should not yield
    records with the same key, but otherwise yield all records, in
    monotonically increasing order of keys. For every key with
    duplicate values, only the first record is yielded. When the
    [=cursor/source=] is an [=/object store=] or an [=/index=] with
    the [=unique flag=] set, this direction has exactly the same
    behavior as {{"next"}}.
  </dd>

  <dt>{{"prev"}}</dt>
  <dd>
    This direction causes the cursor to be opened at the end of the
    [=cursor/source=]. When iterated, the [=cursor=] should yield all
    records, including duplicates, in monotonically decreasing order
    of keys.
  </dd>

  <dt>{{"prevunique"}}</dt>
  <dd>
    This direction causes the cursor to be opened at the end of the
    [=cursor/source=]. When iterated, the [=cursor=] should not
    yield records with the same key, but otherwise yield all records,
    in monotonically decreasing order of keys. For every key with
    duplicate values, only the first record is yielded. When the
    [=cursor/source=] is an [=/object store=] or an
    [=/index=] with the [=unique flag=] set, this direction
    has exactly the same behavior as {{"prev"}}.
  </dd>
</dl>

A [=cursor=] has a <dfn>position</dfn> within its range. It is
possible for the list of records which the cursor is iterating over to
change before the full [=cursor/range=] of the cursor has been iterated.
In order to handle this, cursors maintain their [=cursor/position=] not as
an index, but rather as a [=/key=] of the previously returned
record. For a forward iterating cursor, the next time the cursor is
asked to iterate to the next record it returns the record with the
lowest [=/key=] [=greater than=] the one previously
returned. For a backwards iterating cursor, the situation is opposite
and it returns the record with the highest [=/key=] [=less
than=] the one previously returned.

For cursors iterating indexes the situation is a little bit more
complicated since multiple records can have the same key and are
therefore also sorted by [=/value=]. When iterating indexes the
[=cursor=] also has an <dfn>object store position</dfn>, which
indicates the [=/value=] of the previously found [=object-store/record=] in
the index. Both [=cursor/position=] and the [=object store position=]
are used when finding the next appropriate record.

A [=cursor=] has a <dfn>key</dfn> and a <dfn>value</dfn> which
represent the [=/key=] and the [=/value=] of the last iterated
[=object-store/record=].

A [=cursor=] has a <dfn>got value flag</dfn>. When this flag unset,
the cursor is either in the process of loading the next value or it
has reached the end of its [=cursor/range=]. When it is set, it indicates
that the cursor is currently holding a value and that it is ready to
iterate to the next one.

If the [=cursor/source=] of a cursor is an [=/object store=], the
<dfn>effective object store</dfn> of the cursor is that object store
and the <dfn>effective key</dfn> of the cursor is the cursor's
[=cursor/position=]. If the [=cursor/source=] of a cursor is an [=/index=],
the [=effective object store=] of the cursor is that index's
[=referenced=] object store and the [=effective key=] is the cursor's
[=object store position=].

A [=cursor=] also has a <dfn>key only flag</dfn>, that indicates
whether the cursor's [=cursor/value=] is exposed via the API. Unless
stated otherwise it is unset.

</div>

<!-- ============================================================ -->
<h3 id=key-generator-construct>Key Generators</h3>
<!-- ============================================================ -->

When a [=/object store=] is created it can be specified to use a
<dfn>key generator</dfn>. A [=key generator=] keeps an internal
<dfn>current number</dfn>. The [=current number=] is always a positive
integer. Whenever the key generator is used to generate a new
[=/key=], the generator's [=current number=] is returned and
<strong>then</strong> incremented to prepare for the next time a new
[=/key=] is needed. Implementations must use the following rules for
generating numbers when a [=key generator=] is used.

* Every object store that uses key generators use a separate
    generator. I.e. interacting with one object store never affects
    the key generator of any other object store.

* The [=current number=] of a [=key generator=] is always set to
    1 when the [=/object store=] for that key generator is first
    created.

* When a key generator is used to generate a new [=/key=] for
    a [=/object store=], the key generator's [=current
    number=] is used as the new key value and then the key
    generator's [=current number=] is increased by 1.

* When a [=object-store/record=] is stored and a [=/key=] is specified
    in the call to store the record, if [=key/type=] of the key
    is <i>number</i> and the [=key/value=] is greater than or
    equal to the key generator's [=current number=], then the key
    generator's [=current number=] is set to the smallest integer
    number [=greater than=] the explicit key. A key can be
    specified both for object stores which use [=in-line keys=], by
    setting the property on the stored value which the object store's
    [=object-store/key path=] points to, and for object stores
    which use [=out-of-line keys=], by passing a key argument to
    the call to store the [=object-store/record=].

    <aside class=note>
      Only specified keys of [=key/type=] <i>number</i> may affect the
      [=current number=] of the key generator. Keys of [=key/type=]
      <i>date</i>, <i>array</i> (regardless of the other keys they
      contain), <i>binary</i>, or <i>string</i> (regardless of whether
      they could be parsed as numbers) have no effect on the [=current
      number=] of the key generator. Keys of [=key/type=]
      <i>number</i> with [=key/value=] less than 1 do not affect the
      [=current number=] since they are always lower than the
      [=current number=].
    </aside>

* Modifying a key generator's [=current number=] is considered part
    of a database operation. This means that if the operation fails
    and the operation is reverted, the [=current number=] is
    reverted to the value it had before the operation started. This
    applies both to modifications that happen due to the [=current
    number=] getting increased by 1 when the key generator is used,
    and to modifications that happen due to a [=object-store/record=] being
    stored with a key value specified in the call to store the
    [=object-store/record=].

* Likewise, if a [=/transaction=] is aborted, the [=current
    number=] of the key generator for each [=/object store=] in
    the transaction's [=transaction/scope=] is reverted to the value it had
    before the [=/transaction=] was started.

* When the [=current number=] of a key generator reaches above the
    value 2<sup>53</sup> (9007199254740992) any attempts to use the
    key generator to generate a new [=/key=] will result in a
    "{{ConstraintError}}" {{DOMException}}. It is still possible to insert
    [=object-store/records=] into the object store by specifying an explicit
    key, however the only way to use a key generator again for the
    object store is to delete the object store and create a new one.

    <aside class=note>
      As long as key generators are used in a normal fashion this will
      not be a problem. If you generate a new key 1000 times per
      second day and night, you won't run into this limit for over
      285000 years.
    </aside>

* The [=current number=] for a key generator never decreases, other
    than as a result of database operations being reverted. Deleting a
    [=object-store/record=] from an [=/object store=] never affects the
    object store's key generator. Even clearing all records from an
    object store, for example using the {{IDBObjectStore/clear()}} method, does not
    affect the [=current number=] of the object store's key
    generator.

A practical result of this is that the first key generated for an
object store is always 1 (unless a higher numeric key is inserted
first) and the key generated for an object store is always a positive
integer higher than the highest numeric key in the store. The same key
is never generated twice for the same object store unless a
transaction is rolled back.

<aside class=example>

Each object store gets its own key generator:

<pre class=lang-javascript>
store1 = db.createObjectStore("store1", { autoIncrement: true });
store1.put("a"); // Will get key 1
store2 = db.createObjectStore("store2", { autoIncrement: true });
store2.put("a"); // Will get key 1
store1.put("b"); // Will get key 2
store2.put("b"); // Will get key 2
</pre>

If an insertion fails due to constraint violations or IO error, the
key generator is not updated.

<pre class=lang-javascript>
transaction.onerror = function(e) { e.preventDefault() };
store = db.createObjectStore("store1", { autoIncrement: true });
index = store.createIndex("index1", "ix", { unique: true });
store.put({ ix: "a"}); // Will get key 1
store.put({ ix: "a"}); // Will fail
store.put({ ix: "b"}); // Will get key 2
</pre>

Removing items from an objectStore never affects the key generator.
Including when {{IDBObjectStore/clear()}} is called.

<pre class=lang-javascript>
store = db.createObjectStore("store1", { autoIncrement: true });
store.put("a"); // Will get key 1
store.delete(1);
store.put("b"); // Will get key 2
store.clear();
store.put("c"); // Will get key 3
store.delete(IDBKeyRange.lowerBound(0));
store.put("d"); // Will get key 4
</pre>

Inserting an item with an explicit key affects the key generator if,
and only if, the key is numeric and higher than the last generated
key.

<pre class=lang-javascript>
store = db.createObjectStore("store1", { autoIncrement: true });
store.put("a"); // Will get key 1
store.put("b", 3); // Will use key 3
store.put("c"); // Will get key 4
store.put("d", -10); // Will use key -10
store.put("e"); // Will get key 5
store.put("f", 6.00001); // Will use key 6.0001
store.put("g"); // Will get key 7
store.put("f", 8.9999); // Will use key 8.9999
store.put("g"); // Will get key 9
store.put("h", "foo"); // Will use key "foo"
store.put("i"); // Will get key 10
store.put("j", [1000]); // Will use key [1000]
store.put("k"); // Will get key 11
// All of these would behave the same if the objectStore used a
// keyPath and the explicit key was passed inline in the object
</pre>

Aborting a transaction rolls back any increases to the key generator
which happened during the transaction. This is to make all rollbacks
consistent since rollbacks that happen due to crash never has a chance
to commit the increased key generator value.

<pre class=lang-javascript>
db.createObjectStore("store", { autoIncrement: true });
trans1 = db.transaction(["store"], "readwrite");
store_t1 = trans1.objectStore("store");
store_t1.put("a"); // Will get key 1
store_t1.put("b"); // Will get key 2
trans1.abort();
trans2 = db.transaction(["store"], "readwrite");
store_t2 = trans2.objectStore("store");
store_t2.put("c"); // Will get key 1
store_t2.put("d"); // Will get key 2
</pre>
</aside>

<aside class=example>

The following examples illustrate the different behaviors when trying
to use in-line [=/keys=] and [=key generators=] to save an object
to an [=/object store=].

If the following conditions are true:

* The [=/object store=] has a [=key generator=].

* There is no in-line value for the [=object-store/key path=]
    property.

Then the value provided by the [=key generator=] is used to populate
the key value. In the example below the [=object-store/key path=] for
the object store is "<code>foo.bar</code>". The actual object has no
value for the <code>bar</code> property, <code>{ foo: {} }</code>.
When the object is saved in the [=/object store=] the <code>bar</code>
property is assigned a value of 1 because that is the next [=/key=]
generated by the [=key generator=].

<pre class=lang-javascript>
var store = db.createObjectStore("store", { keyPath: "foo.bar",
                                            autoIncrement: true });
store.put({ foo: {} }).onsuccess = function(e) {
  var key = e.target.result;
  console.assert(key === 1);
};
</pre>

If the following conditions are true:

* The [=/object store=] has a [=key generator=].

* There is a value for the [=object-store/key path=]
    property.

Then the value associated with the [=object-store/key path=]
property is used. The auto-generated [=/key=] is not used. In the
example below the [=object-store/key path=] for the [=/object
store=] is "<code>foo.bar</code>". The actual object has a value of
10 for the <code>bar</code> property, <code>{ foo: { bar: 10}
}</code>. When the object is saved in the [=/object store=] the
<code>bar</code> property keeps its value of 10, because that is the
key value.

<pre class=lang-javascript>
var store = db.createObjectStore("store", { keyPath: "foo.bar",
                                            autoIncrement: true });
store.put({ foo: { bar: 10 } }).onsuccess = function(e) {
  var key = e.target.result;
  console.assert(key === 10);
};
</pre>

The following example illustrates the scenario when the specified
in-line [=/key=] is defined through a [=object-store/key
path=] but there is no property matching it. The value provided by
the [=key generator=] is then used to populate the key value and
the system is responsible for creating as many properties as it
requires to suffice the property dependencies on the hierarchy chain.
In the example below the [=object-store/key path=] for the
[=/object store=] is "<code>foo.bar.baz</code>". The actual
object has no value for the <code>foo</code> property, <code>{ zip: {}
}</code>. When the object is saved in the [=/object store=]
the <code>foo</code>, <code>bar</code>, and <code>baz</code>
properties are created each as a child of the other until a value for
<code>foo.bar.baz</code> can be assigned. The value for
<code>foo.bar.baz</code> is the next key generated by the object
store.

<pre class=lang-javascript>
var store = db.createObjectStore("store", { keyPath: "foo.bar.baz",
                                            autoIncrement: true });
store.put({ zip: {} }).onsuccess = function(e) {
  var key = e.target.result;
  console.assert(key === 1);
  store.get(key).onsuccess = function(e) {
    var value = e.target.result;
    // value will be: { zip: {}, foo: { bar: { baz: 1 } } }
    console.assert(value.foo.bar.baz === 1);
  };
};
</pre>

Attempting to store a property on a primitive value will fail and
throw an error. In the first example below the [=object-store/key
path=] for the object store is "<code>foo</code>". The actual object
is a primitive with the value, <code>4</code>. Trying to define a
property on that primitive value fails. The same is true for arrays.
Properties are not allowed on an array. In the second example below,
the actual object is an array, <code>[10]</code>. Trying to define a
property on the array fails.

<pre class=lang-javascript>
var store = db.createObjectStore("store", { keyPath: "foo", autoIncrement: true });

// The key generation will attempt to create and store the key path
// property on this primitive.
store.put(4); // will throw DataError

// The key generation will attempt to create and store the key path
// property on this array.
store.put([10]); // will throw DataError
</pre>
</aside>


<!-- ============================================================ -->
<h2 id=exceptions>Exceptions</h2>
<!-- ============================================================ -->

Each of the exceptions used in this document is a
{{DOMException}} with a specific type. The exception types and
properties such as legacy code value are defined in [[!WEBIDL]].

The table below lists the {{DOMException}}s used in this
document along with a description of the exception type's
usage.

<table class=props>
  <tr>
    <th>Type</th>
    <th>Description</th>
  </tr>
    <tr>
    <td>{{AbortError}}</td>
    <td>A request was aborted.</td>
  </tr>
  <tr>
    <td>{{ConstraintError}}</td>
    <td>
      A mutation operation in the transaction failed because a
      constraint was not satisfied.
    </td>
  </tr>
  <tr>
    <td>{{DataCloneError}}</td>
    <td>
      The data being stored could not be cloned by the internal
      structured cloning algorithm.
    </td>
  </tr>
  <tr>
    <td>{{DataError}}</td>
    <td>Data provided to an operation does not meet requirements.</td>
  </tr>
  <tr>
    <td>{{InvalidAccessError}}</td>
    <td>An invalid operation was performed on an object.</td>
  </tr>
  <tr>
    <td>{{InvalidStateError}}</td>
    <td>
      An operation was called on an object on which it is not allowed
      or at a time when it is not allowed, or if a request is made on
      a source object that has been deleted or removed.
    </td>
  </tr>
  <tr>
    <td>{{NotFoundError}}</td>
    <td>
      The operation failed because the requested database object could
      not be found.
    </td>
  </tr>
  <tr>
    <td>{{QuotaExceededError}}</td>
    <td>
      The operation failed because there was not enough remaining
      storage space, or the storage quota was reached and the user
      declined to give more space to the database.
    </td>
  </tr>
  <tr>
    <td>{{SyntaxError}}</td>
    <td>The keyPath argument contains an invalid key path.</td>
  </tr>
  <tr>
    <td>{{ReadOnlyError}}</td>
    <td>The mutating operation was attempted in a read-only transaction.</td>
  </tr>
  <tr>
    <td>{{TransactionInactiveError}}</td>
    <td>
      A request was placed against a transaction which is currently
      not active, or which is finished.
    </td>
  </tr>
  <tr>
    <td>{{UnknownError}}</td>
    <td>
      The operation failed for reasons unrelated to the database
      itself and not covered by any other errors.
    </td>
  </tr>
  <tr>
    <td>{{VersionError}}</td>
    <td>
      An attempt was made to open a database using a lower version
      than the existing version.
    </td>
  </tr>
</table>

<aside class=note>
  Given that multiple Indexed DB operations can throw the same type of
  error, and that a even single operation can throw the same type of
  error for multiple reasons, implementations are encouraged to
  provide more specific messages to enable developers to identify the
  cause of errors.
</aside>


<!-- ============================================================ -->
<h2 id=async-api>API</h2>
<!-- ============================================================ -->

The API methods return without blocking the calling thread. All
asynchronous operations immediately return an {{IDBRequest}}
instance. This object does not initially contain any information about
the result of the operation. Once information becomes available, an
event is fired on the request and the information becomes available
through the properties of the {{IDBRequest}} instance.

The <span>task source</span> for these tasks is the <dfn>database
access task source</dfn>.


<!-- ============================================================ -->
<h3 id=request-api>The {{IDBRequest}} interface</h3>
<!-- ============================================================ -->

The {{IDBRequest}} interface provides the means to access results of
asynchronous requests to [=databases=] and [=database=] objects using
[=event handler IDL attributes=] [[!HTML]].

Every method for making asynchronous requests returns an
{{IDBRequest}} object that communicates back to the requesting
application through events. This design means that any number of
requests can be active on any [=database=] at a time.

<aside class=example>

In the following example, we open a [=database=] asynchronously.
Various event handlers are registered for responding to various
situations.

<pre class=lang-javascript>
var request = indexedDB.open('AddressBook', 15);
request.onsuccess = function(evt) {...};
request.onerror = function(evt) {...};
</pre>
</aside>

<pre class=idl>
[Exposed=(Window,Worker)]
interface IDBRequest : EventTarget {
  readonly attribute any                                        result;
  readonly attribute DOMException?                              error;
  readonly attribute (IDBObjectStore or IDBIndex or IDBCursor)? source;
  readonly attribute IDBTransaction?                            transaction;
  readonly attribute IDBRequestReadyState                       readyState;

  // Event handlers:
  attribute EventHandler onsuccess;
  attribute EventHandler onerror;
};

enum IDBRequestReadyState {
  "pending",
  "done"
};
</pre>

<div class=note>
  <dl class=domintro>
    <dt><var>request</var> . {{IDBRequest/result}}</dt>
    <dd>
        When a request is completed, returns the [=request/result=],
        or <code>undefined</code> if the request failed. Throws a
        "{{InvalidStateError}}" {{DOMException}} if the request is still pending.
    </dd>

    <dt><var>request</var> . {{IDBRequest/error}}</dt>
    <dd>
        When a request is completed, returns the [=request/error=] (a
        {{DOMException}}), or null if the request succeeded. Throws
        a "{{InvalidStateError}}" {{DOMException}} if the request is still pending.
    </dd>

    <dt><var>request</var> . {{IDBRequest/source}}</dt>
    <dd>
        Returns the {{IDBObjectStore}}, {{IDBIndex}}, or {{IDBCursor}}
        the request was made against, or null if is was an [=open
        request=].
    </dd>

    <dt><var>request</var> . {{IDBRequest/transaction}}</dt>
    <dd>
        Returns the {{IDBTransaction}} the request was made within.
        If this as an [=open request=], then it returns an
        [=upgrade transaction=] while it is running, or null otherwise.
    </dd>

    <dt><var>request</var> . {{IDBRequest/readyState}}</dt>
    <dd>
        Returns {{"pending"}} until a request is complete,
        then returns {{"done"}}.
    </dd>
  </dl>
</div>

The <dfn attribute for=IDBRequest>result</dfn> attribute's getter must
[=throw=] an "{{InvalidStateError}}" {{DOMException}} if the [=request/done flag=] is
unset. Otherwise, the attribute's getter must return the
[=request/result=] of the request, or undefined if the
request resulted in an error.


The <dfn attribute for=IDBRequest>error</dfn> attribute's getter must
[=throw=] an "{{InvalidStateError}}" {{DOMException}} if the [=request/done flag=] is unset.
Otherwise, the attribute's getter must return the [=request/error=] of
the request, or null if no error occurred.

The <dfn attribute for=IDBRequest>source</dfn> attribute's getter must
return the [=request/source=] of the [=request=], or null if no
[=request/source=] is set.

The <dfn attribute for=IDBRequest>transaction</dfn> attribute's getter
must return the [=request/transaction=] of the [=request=]. This
property can be null for certain requests, such as for [=requests=]
returned from {{IDBFactory/open()}}.

The <dfn attribute for=IDBRequest>readyState</dfn> attribute's getter
must return {{"pending"}} if the [=request/done flag=] is unset, and
{{"done"}} otherwise.


The <dfn attribute for=IDBRequest>onsuccess</dfn> attribute is the
event handler for the <code>success</code> event.

The <dfn attribute for=IDBRequest>onerror</dfn> attribute is the event
handler for the <code>error</code> event.


Methods on {{IDBDatabase}} that return a [=open request=] use an
extended interface to allow listening to the
<code>[=request/blocked=]</code> event and
<code>[=upgradeneeded=]</code> event.

<pre class=idl>
[Exposed=(Window,Worker)]
interface IDBOpenDBRequest : IDBRequest {
  // Event handlers:
  attribute EventHandler onblocked;
  attribute EventHandler onupgradeneeded;
};
</pre>

The <dfn attribute for=IDBOpenDBRequest>onblocked</dfn> attribute is
the event handler for the <code>[=request/blocked=]</code> event.

The <dfn attribute for=IDBOpenDBRequest>onupgradeneeded</dfn>
attribute is the event handler for the
<code>[=upgradeneeded=]</code> event.


<!-- ============================================================ -->
<h3 id=events>Event interfaces</h3>
<!-- ============================================================ -->

This specification fires events with the following custom interfaces:

<pre class=idl>
[Exposed=(Window,Worker),
 Constructor(DOMString type, optional IDBVersionChangeEventInit eventInitDict)]
interface IDBVersionChangeEvent : Event {
  readonly attribute unsigned long long  oldVersion;
  readonly attribute unsigned long long? newVersion;
};

dictionary IDBVersionChangeEventInit : EventInit {
  unsigned long long  oldVersion = 0;
  unsigned long long? newVersion = null;
};
</pre>

The <dfn attribute for=IDBVersionChangeEvent>oldVersion</dfn>
attribute getter returns the previous version of the database.


The <dfn attribute for=IDBVersionChangeEvent>newVersion</dfn>
attribute getter returns the new version of the database, or null if
the database is being deleted. See the [=steps for running an upgrade
transaction=].

Events are constructed as defined in <a
href="https://www.w3.org/TR/domcore/#constructing-events">Constructing
events</a>, in [[!DOM]].

To <dfn>fire a version change event</dfn> named |e| at |target| given
|oldVersion| and |newVersion|, dispatch an event at |target|. The
event must use the {{IDBVersionChangeEvent}} interface with its
{{Event/type}} set to |e|, its {{IDBVersionChangeEvent/oldVersion}}
attribute set to |oldVersion|, and its
{{IDBVersionChangeEvent/newVersion}} attribute set to |newVersion|.
This event must not bubble or be cancelable.


<!-- ============================================================ -->
<h3 id=factory-interface>The {{IDBFactory}} interface</h3>
<!-- ============================================================ -->

[=Database=] objects are accessed through methods on the
{{IDBFactory}} interface. A single object implementing this
interface is present in the global scope of environments that support
Indexed DB operations.

<pre class=idl>
partial interface WindowOrWorkerGlobalScope {
  [SameObject] readonly attribute IDBFactory indexedDB;
};
</pre>

The <dfn attribute for=WindowOrWorkerGlobalScope>indexedDB</dfn>
attribute provides applications a mechanism for accessing capabilities
of indexed databases.

<pre class=idl>
[Exposed=(Window,Worker)]
interface IDBFactory {
  IDBOpenDBRequest open(DOMString name,
                        [EnforceRange] optional unsigned long long version);
  IDBOpenDBRequest deleteDatabase(DOMString name);

  short cmp(any first, any second);
};
</pre>


<div class=note>
  <dl class=domintro>
    <dt><var>request</var> = indexedDB .
        {{IDBFactory/open()|open}}(<var>name</var>)</dt>
    <dd>
        Attempts to open a [=/connection=] to the named [=/database=]
        with the current version, or 1 if it does not already exist.
        If the request is successful |request|'s
        {{IDBRequest/result}} will be the [=/connection=].
    </dd>
    <dt><var>request</var> = indexedDB .
        {{IDBFactory/open()|open}}(<var>name</var>, <var>version</var>)</dt>
    <dd>
        Attempts to open a [=/connection=] to the named [=/database=]
        with the specified version. If the database already exists
        with a lower version and there are open [=/connections=]
        that don't close in response to a
        <code>versionchange</code> event, the request will be
        [=request/blocked=] until all they close, then an upgrade
        will occur. If the database already exists with a higher
        version the request will fail. If the request is
        successful |request|'s {{IDBRequest/result}} will
        be the [=/connection=].
    </dd>
    <dt><var>request</var> = indexedDB .
        {{IDBFactory/deleteDatabase()|deleteDatabase}}(<var>name</var>)</dt>
    <dd>
        Attempts to delete the named [=/database=]. If the
        database already exists and there are open
        [=/connections=] that don't close in response to a
        <code>versionchange</code> event, the request will be
        [=request/blocked=] until all they close. If the request
        is successful |request|'s {{IDBRequest/result}}
        will be null.
    </dd>
  </dl>
</div>

The <dfn method for=IDBFactory>open(|name|, |version|)</dfn> method,
when invoked, must run these steps:

<div class=algorithm>

1. If |version| is 0 (zero), [=throw=] a [=TypeError=].

2. Let |request| be a new [=open request=].

3. Run the following substeps in parallel:

    1. Let |result| be the result of running the [=steps for
        opening a database=], with the origin of the
        global scope used to access this {{IDBFactory}},
        |name|, |version| if given and undefined
        otherwise, and |request|.

        <aside class=note>
          If |version| is not given and a [=database=]
          with that name already exists, a connection will be opened
          without changing the [=database/version=]. If
          |version| is not given and no [=database=] with
          that name exists, a new [=database=] will be created with
          [=database/version=] equal to 1.
        </aside>

    2. [=Queue a task=] to run these substeps:

        1. If |result| is an error, set the [=request/error=]
            of |request| to |result| and dispatch an event at
            |request|. The event must use the [=Event=] interface
            and set the {{Event/type}} attribute to
            "<code>error</code>". The event does bubble but is not
            cancelable.

        2. Otherwise, set the [=request/result=] of |request|
            to |result| and dispatch an event at |request|. The event
            must use the [=Event=] interface and set the
            {{Event/type}} attribute to "<code>success</code>". The
            event does not bubble and is not cancelable. If the steps
            above resulted in an [=upgrade transaction=] being run,
            then firing the "<code>success</code>" event must be done
            after the [=upgrade transaction=] completes.

            <aside class=note>
              The last requirement is to ensure that in case another
              version upgrade is about to happen, the success event is
              fired on the connection first so that the script gets a
              chance to register a listener for the
              <code>versionchange</code> event.
            </aside>

            <aside class=note>
              The firing of "<code>success</code>" or "<code>error</code>"
              events do not follow the normal steps to [=fire a success
              event=] or [=fire an error event=] as there is no
              active transaction at the time when they fire.
            </aside>

4. Return a new {{IDBOpenDBRequest}} object for |request|.

</div>

The <dfn method for=IDBFactory>deleteDatabase(|name|)</dfn> method,
when invoked, must run these steps:

<div class=algorithm>

1. Let |request| be a new [=open request=].

3. Run the following substeps in parallel:

    1. Let |result| be the result of running the [=steps for
        deleting a database=], with the origin of the
        global scope used to access this {{IDBFactory}},
        |name|, and |request|.

    2. [=Queue a task=] to run these substeps:
        1. If |result| is an error set the [=request/error=] of
            |request| to |result| and dispatch an event at |request|.
            The event must use the [=Event=] interface and set the
            {{Event/type}} attribute to "<code>error</code>". The
            event does bubble but is not cancelable.

        2. Otherwise, set the [=request/result=] of |request|
            to undefined and [=fire a version change event=] named
            <code>success</code> at [=request=] with |result| and
            null.

            <aside class=note>
              The firing of "<code>success</code>" or "<code>error</code>"
              events do not follow the normal steps to [=fire a success
              event=] or [=fire an error event=] as there is no
              active transaction at the time when they fire.
            </aside>

3. Return a new {{IDBOpenDBRequest}} object for |request|.

</div>

<div class=note>
  <dl class=domintro>
    <dt><var>result</var> = indexedDB .
        {{IDBFactory/cmp()|cmp}}(<var>key1</var>, <var>key2</var>)</dt>
    <dd>
        Compares two values as [=/keys=]. Returns -1 if
        |key1| precedes |key2|, 1 if
        |key2| precedes |key1|, and 0 if
        the keys are equal.

        Throws a "{{DataError}}" {{DOMException}} if either input is not a valid [=/key=].
    </dd>
  </dl>
</div>

The <dfn method for=IDBFactory>cmp(|first|, |second|)</dfn> method,
when invoked, must run these steps:

<div class=algorithm>

1. Let |a| be the result of running the steps to [=convert a
    value to a key=] with |first|. Rethrow any exceptions.

2. If |a| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

3. Let |b| be the result of running the steps to [=convert a
    value to a key=] with |second|. Rethrow any exceptions.

4. If |b| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

5. Return the results of running the steps to [=compare two keys=]
    with |a| and |b|.

</div>

<!-- ============================================================ -->
<h3 id=database-interface>The {{IDBDatabase}} interface</h3>
<!-- ============================================================ -->

The {{IDBDatabase}}
interface represents a [=/connection=] to a [=database=].

An {{IDBDatabase}} object must not be garbage collected if its
associated [=/connection=]'s [=close pending flag=] is unset and it
has one or more event listeners registers whose type is one of
<code>abort</code>, <code>error</code>, or <code>versionchange</code>.
If an {{IDBDatabase}} object is garbage collected, the associated
[=/connection=] must be [=connection/closed=].

<pre class=idl>
[Exposed=(Window,Worker)]
interface IDBDatabase : EventTarget {
  readonly attribute DOMString          name;
  readonly attribute unsigned long long version;
  readonly attribute DOMStringList      objectStoreNames;

  IDBTransaction transaction((DOMString or sequence&lt;DOMString&gt;) storeNames,
                             optional IDBTransactionMode mode = "readonly");
  void           close();

  IDBObjectStore createObjectStore(DOMString name,
                                   optional IDBObjectStoreParameters options);
  void           deleteObjectStore(DOMString name);

  // Event handlers:
  attribute EventHandler onabort;
  attribute EventHandler onclose;
  attribute EventHandler onerror;
  attribute EventHandler onversionchange;
};

dictionary IDBObjectStoreParameters {
  (DOMString or sequence&lt;DOMString&gt;)? keyPath = null;
  boolean                             autoIncrement = false;
};
</pre>

<div class=note>
  <dl class=domintro>
    <dt><var>connection</var> . {{IDBDatabase/name}}</dt>
    <dd>
        Returns the [=database/name=] of the database.
    </dd>
    <dt><var>connection</var> . {{IDBDatabase/version}}</dt>
    <dd>
        Returns the [=database/version=] of the database.
    </dd>
  </dl>
</div>

The <dfn attribute for=IDBDatabase>name</dfn> attribute's getter must
return the [=database/name=] of the [=connected=]
[=database=]. The attribute must return this name even if the
[=close pending flag=] is set on the [=/connection=]. In
other words, the value of this attribute stays constant for the
lifetime of the {{IDBDatabase}} instance.


The <dfn attribute for=IDBDatabase>version</dfn> attribute's getter
must return this [=/connection=]'s
[=connection/version=].

<aside class=note>
  As long as the [=/connection=] is open, this is the same as the
  connected [=database=]'s [=database/version=]. Once the
  [=/connection=] has [=connection/closed=], this attribute will not
  reflect changes made with a later [=upgrade transaction=].
</aside>

<div class=note>
  <dl class=domintro>

    <dt><var>connection</var> . {{IDBDatabase/objectStoreNames}}</dt>
    <dd>
        Returns a list of the names of [=/object stores=] in the database.
    </dd>

    <dt><var>store</var> = <var>connection</var> .
        {{IDBDatabase/createObjectStore()|createObjectStore}}(<var>name</var>
            [, <var>options</var>])</dt>
    <dd>
        Creates a new [=/object store=] with the given |name| and |options|
        and returns a new {{IDBObjectStore}}.

        Throws a "{{InvalidStateError}}" {{DOMException}} if not called within an
        [=upgrade transaction=].
    </dd>

    <dt><var>connection</var> .
        {{IDBDatabase/deleteObjectStore()|deleteObjectStore}}(<var>name</var>)</dt>
    <dd>
        Deletes the [=/object store=] with the given |name|.

        Throws a "{{InvalidStateError}}" {{DOMException}} if not called within an
        [=upgrade transaction=].
    </dd>
  </dl>
</div>

The <dfn attribute for=IDBDatabase>objectStoreNames</dfn> attribute's
getter must return a [=sorted list=] of the [=object-store/names=] of
the [=/object stores=] in this [=/connection=]'s [=object store set=].

<aside class=note>
  As long as the [=/connection=] is open, this is the same as the
  connected [=database=]'s [=/object store=] [=object-store/names=].
  Once the [=/connection=] has [=connection/closed=], this attribute
  will not reflect changes made with a later [=upgrade transaction=].
</aside>


The <dfn method for=IDBDatabase>createObjectStore(|name|,
|options|)</dfn> method, when invoked, must run these steps:

<div class=algorithm>

1. Let |database| be the [=database=] associated with this
    [=/connection=].

2. Let |transaction| be the [=upgrade transaction=] associated with
    |database|. If one does not exist or it is
    [=transaction/finished=], [=throw=] an "{{InvalidStateError}}"
    {{DOMException}}.

3. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

4. Let |keyPath| be |options|'s {{IDBObjectStoreParameters/keyPath}}
    member if it is not undefined or null, or null otherwise.

5. If |keyPath| is not null and is not a [=valid key
    path=], [=throw=] a "{{SyntaxError}}" {{DOMException}}.

6. If an [=/object store=] [=object-store/named=] |name| already
    exists in |database| [=throw=] a "{{ConstraintError}}" {{DOMException}}.

7. Let |autoIncrement| be set if |options|'s
    {{IDBObjectStoreParameters/autoIncrement}} member is true, or
    unset otherwise.

8. If |autoIncrement| is set and |keyPath| is an empty string or any
    sequence (empty or otherwise), [=throw=] an
    "{{InvalidAccessError}}" {{DOMException}}.

9. Let |store| be a new [=/object store=] in
    |database|. Set the created [=/object store=]'s
    [=object-store/name=] to |name|. If
    |autoIncrement| is set, then the created [=/object
    store=] uses a [=key generator=]. If |keyPath| is
    not null, set the created [=/object store=]'s
    [=object-store/key path=] to |keyPath|.

10. Return a new [=/object store handle=] associated with
    |store| and |transaction|.

</div>

This method creates and returns a new [=/object store=] with the given
name in the [=connected=] [=database=]. Note that this method must
only be called from within an [=upgrade transaction=].

This method synchronously modifies the
{{IDBDatabase/objectStoreNames}} property on the {{IDBDatabase}}
instance on which it was called.

In some implementations it is possible for the implementation to run
into problems after queuing a task to create the [=/object store=]
after the {{createObjectStore()}} method has returned. For example in
implementations where metadata about the newly created [=/object
store=] is inserted into the database asynchronously, or where the
implementation might need to ask the user for permission for quota
reasons. Such implementations must still create and return an
{{IDBObjectStore}} object, and once the implementation determines that
creating the [=/object store=] has failed, it must abort the
transaction using the [=steps for aborting a transaction=] using the
appropriate error. For example if creating the [=/object store=]
failed due to quota reasons, a "{{QuotaExceededError}}" {{DOMException}} must be used as
error.


The <dfn method for=IDBDatabase>deleteObjectStore(|name|)</dfn>
method, when invoked, must run these steps:

<div class=algorithm>

1. Let |database| be the [=database=] associated with this
    [=/connection=].

2. Let |transaction| be the [=upgrade transaction=] associated with
    |database|. If one does not exist or it is
    [=transaction/finished=], [=throw=] an "{{InvalidStateError}}"
    {{DOMException}}.

3. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

4. Let |store| be the [=/object store=]
    [=object-store/named=] |name| in |database|,
    or [=throw=] a "{{NotFoundError}}" {{DOMException}} if none.

5. Remove |store| from this [=/connection=]'s [=object
    store set=].

6. If there is an [=/object store handle=] associated with
    |store| and |transaction|, remove all entries from its
    [=object-store-handle/index set=].

7. Destroy |store|.

</div>

This method destroys the [=/object store=] with the given name in the
[=connected=] [=database=]. Note that this method must only be called
from within an [=upgrade transaction=].

This method synchronously modifies the
{{IDBDatabase/objectStoreNames}} property on the {{IDBDatabase}}
instance on which it was called.


<div class=note>
  <dl class=domintro>
    <dt><var>transaction</var> = <var>connection</var> .
        {{IDBDatabase/transaction()|transaction}}(<var>scope</var>
        [, <var>mode</var> = "readonly"])</dt>
    <dd>
        Returns a new [=/transaction=] with the given |mode|
        ({{"readonly"}} or {{"readwrite"}})
        and |scope| which can be a single [=/object store=]
        [=object-store/name=] or an array of
        [=object-store/names=].
    </dd>

    <dt><var>connection</var> . {{IDBDatabase/close()|close}}()</dt>
    <dd>
        Closes the [=/connection=] once all running [=/transactions=]
        have finished.
    </dd>
  </dl>
</div>

The <dfn method for=IDBDatabase>transaction(|storeNames|,
|mode|)</dfn> method, when invoked, must run these steps:

<div class=algorithm>

1. If |mode| parameter is not {{"readonly"}} or {{"readwrite"}},
    [=throw=] a [=TypeError=].

2. If this method is called on {{IDBDatabase}} object for which an
    [=upgrade transaction=] is still running, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

3. If this method is called on an {{IDBDatabase}} instance where the
    [=close pending flag=] is set, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. Let |scope| be the set of unique strings in |storeNames| if it is a
    sequence, or a set containing one string equal to |storeNames|
    otherwise.

5. If any string in |scope| is not the name of an [=/object
    store=] in the [=connected=] [=database=], [=throw=] a
    "{{NotFoundError}}" {{DOMException}}.

6. If |scope| is empty, [=throw=] an "{{InvalidAccessError}}" {{DOMException}}.

7. Let |transaction| be a newly [=transaction/created=] [=/transaction=] with
    |connection|, |mode| and the set of [=/object stores=] named in
    |scope|.

8. When control is returned to the event loop, the implementation must
    unset the [=transaction/active flag=].

9. Return an {{IDBTransaction}} object representing |transaction|.

</div>

<aside class=note>
  The created |transaction| will follow the [=transaction/lifetime=]
  rules.
</aside>


The <dfn method for=IDBDatabase>close()</dfn> method, when invoked,
must run these steps:

<div class=algorithm>

1. Run the [=steps for closing a database connection=] with this
    [=/connection=].

</div>

The <dfn attribute for=IDBDatabase>onabort</dfn> attribute is the
event handler for the <code>abort</code> event.

The <dfn attribute for=IDBDatabase>onclose</dfn> attribute is the
event handler for the <code>close</code> event.

<aside class=advisement>
  &#x1F6A7;
  The {{IDBDatabase/onclose}} attribute is new in this edition.
  It is supported in Chrome 31 and Firefox 50.
  &#x1F6A7;
</aside>

The <dfn attribute for=IDBDatabase>onerror</dfn> attribute is the
event handler for the <code>error</code> event.

The <dfn attribute for=IDBDatabase>onversionchange</dfn> attribute is
the event handler for the <code>versionchange</code> event.


<!-- ============================================================ -->
<h3 id=object-store-interface>The {{IDBObjectStore}} interface</h3>
<!-- ============================================================ -->

The {{IDBObjectStore}}
interface represents an [=/object store handle=].

<pre class=idl>
[Exposed=(Window,Worker)]
interface IDBObjectStore {
           attribute DOMString      name;
  readonly attribute any            keyPath;
  readonly attribute DOMStringList  indexNames;
  readonly attribute IDBTransaction transaction;
  readonly attribute boolean        autoIncrement;

  IDBRequest put(any value, optional any key);
  IDBRequest add(any value, optional any key);
  IDBRequest delete(any query);
  IDBRequest clear();
  IDBRequest get(any query);
  IDBRequest getKey(any query);
  IDBRequest getAll(optional any query,
                    [EnforceRange] optional unsigned long count);
  IDBRequest getAllKeys(optional any query,
                        [EnforceRange] optional unsigned long count);
  IDBRequest count(optional any query);

  IDBRequest openCursor(optional any query,
                        optional IDBCursorDirection direction = "next");
  IDBRequest openKeyCursor(optional any query,
                           optional IDBCursorDirection direction = "next");

  IDBIndex   index(DOMString name);

  IDBIndex   createIndex(DOMString name,
                         (DOMString or sequence&lt;DOMString&gt;) keyPath,
                         optional IDBIndexParameters options);
  void       deleteIndex(DOMString indexName);
};

dictionary IDBIndexParameters {
  boolean unique = false;
  boolean multiEntry = false;
};
</pre>


<div class=note>
  <dl class=domintro>
    <dt><var>store</var> . {{IDBObjectStore/name}}</dt>
    <dd>
        Returns the [=object-store/name=] of the store.
    </dd>
    <dt><var>store</var> . {{IDBObjectStore/name}} = <var>newName</var></dt>
    <dd>
        Updates the [=object-store/name=] of the store to |newName|.

        Throws "{{InvalidStateError}}" {{DOMException}} if not called within an [=upgrade
        transaction=].
    </dd>
    <dt><var>store</var> . {{IDBObjectStore/keyPath}}</dt>
    <dd>
        Returns the [=object-store/key path=] of the store, or null if none.
    </dd>
    <dt><var>list</var> . {{IDBObjectStore/indexNames}}</dt>
    <dd>
        Returns a list of the names of indexes in the store.
    </dd>
    <dt><var>store</var> . {{IDBObjectStore/transaction}}</dt>
    <dd>
        Returns the associated [=/transaction=].
    </dd>
    <dt><var>store</var> . {{IDBObjectStore/autoIncrement}}</dt>
    <dd>
        Returns true if the store has a [=key generator=], and false otherwise.
    </dd>
  </dl>
</div>


The <dfn attribute for=IDBObjectStore>name</dfn> attribute's getter
must return this [=/object store handle=]'s
[=object-store/name=].

<aside class=note>
  As long as the [=/transaction=] has not [=transaction/finished=],
  this is the same as the associated [=/object store=]'s
  [=object-store/name=]. Once the [=/transaction=] has
  [=transaction/finished=], this attribute will not reflect changes made with a
  later [=upgrade transaction=].
</aside>


The {{IDBObjectStore/name}} attribute's setter must run these steps:

<div class=algorithm>

1. Let |name| be the given value.

2. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

3. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

4. If |store| has been deleted,
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

5. If |transaction| is not an [=upgrade transaction=],
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

6. If |transaction| is not [=transaction/active=],
    [=throw=] a "{{TransactionInactiveError}}" {{DOMException}}.

7. If |store|'s [=object-store/name=] is equal to |name|,
    terminate these steps.

8. If an [=/object store=] [=object-store/named=]
    |name| already exists in |store|'s [=database=], [=throw=] a
    "{{ConstraintError}}" {{DOMException}}.

9. Set |store|'s [=object-store/name=] to |name|.

10. Set this [=/object store handle=]'s
    [=object-store-handle/name=] to |name|.

</div>

<aside class=advisement>
  &#x1F6A7;
  The {{IDBObjectStore/name}} attribute's setter is new in this edition.
  It will be supported in Firefox 51.
  &#x1F6A7;
</aside>


The <dfn attribute for=IDBObjectStore>keyPath</dfn> attribute's getter
must return this [=/object store handle=]'s
[=object-store-handle/object store=]'s [=object-store/key
path=], or null if none.

The conversion is done following the normal [[!WEBIDL]] binding logic
for {{DOMString}} and [=sequence&lt;DOMString&gt;=] values, as
appropriate.

The returned value is not the same instance that was used when the
[=/object store=] was created. However, if this attribute returns
an object (specifically an [=Array=]), it returns the same object
instance every time it is inspected. Changing the properties of the
object has no effect on the [=/object store=].


The <dfn attribute for=IDBObjectStore>indexNames</dfn> attribute's
getter must return a [=sorted list=] of the [=index/names=]
of [=/indexes=] in this [=/object store handle=]'s
[=index set=].

<aside class=note>
  As long as the [=/transaction=] has not [=transaction/finished=],
  this is the same as the associated [=/object store=]'s list
  of [=/index=] [=index/names=]. Once the
  [=/transaction=] has [=transaction/finished=], this attribute will not
  reflect changes made with a later [=upgrade transaction=].
</aside>


The <dfn attribute for=IDBObjectStore>transaction</dfn> attribute's
getter must return this [=/object store handle=]'s
[=object-store-handle/transaction=].


The <dfn attribute for=IDBObjectStore>autoIncrement</dfn> attribute's
getter must return true if this [=/object store handle=]'s
[=object-store-handle/object store=] has a [=key generator=],
and false otherwise.


<div class=note>
  The following methods throw a "{{ReadOnlyError}}" {{DOMException}} if called within a
  [=read-only transaction=], and a "{{TransactionInactiveError}}" {{DOMException}} if
  called when the [=/transaction=] is not [=transaction/active=].

  <dl class=domintro>
    <dt>
      <var>request</var> = <var>store</var>
          . {{IDBObjectStore/put()|put}}(<var>value</var> [, <var>key</var>])
    </dt>
    <dt>
      <var>request</var> = <var>store</var>
          . {{IDBObjectStore/add()|add}}(<var>value</var> [, <var>key</var>])
    </dt>
    <dd>
       Adds or updates a [=object-store/record=] in |store| with the given |value|
       and |key|. If the store uses [=in-line keys=], then |key| must
       not be specified, or a "{{DataError}}" {{DOMException}} will be thrown.

       If {{IDBObjectStore/put()}} is used, any existing [=object-store/record=]
       with the [=/key=] will be replaced. If {{IDBObjectStore/add()}}
       is used, and if a [=object-store/record=] with the [=/key=] already exists
       the |request| will fail, with |request|'s {{IDBRequest/error}}
       set to a "{{ConstraintError}}" {{DOMException}}.

       If successful, |request|'s {{IDBRequest/result}} will be the
       [=object-store/record=]'s [=/key=].
    </dd>

    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBObjectStore/delete()|delete}}(<var>query</var>)
    </dt>
    <dd>
       Deletes [=object-store/records=] in |store| with the given
       [=/key=] or in the given [=key range=] in |query|.

       If successful, |request|'s {{IDBRequest/result}} will
       be <code>undefined</code>.
    </dd>

    <dt>
      <var>request</var> = <var>store</var> . {{IDBObjectStore/clear()|clear}}()
    </dt>
    <dd>
       Deletes all [=object-store/records=] in |store|.

       If successful, |request|'s {{IDBRequest/result}} will
       be <code>undefined</code>.
    </dd>
  </dl>
</div>

The <dfn method for=IDBObjectStore>put(|value|, |key|)</dfn> method,
when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted,
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=],
    [=throw=] a "{{TransactionInactiveError}}" {{DOMException}}.

5. If |transaction| is a [=read-only transaction=],
    [=throw=] a "{{ReadOnlyError}}" {{DOMException}}.

6. If |store| uses [=in-line keys=] and |key| was given,
    [=throw=] a "{{DataError}}" {{DOMException}}.

7. If |store| uses [=out-of-line keys=] and has no [=key
    generator=] and |key| was not given, [=throw=] a
    "{{DataError}}" {{DOMException}}.

8. If |key| was given, run these substeps:

    1. Let |r| be the result of running the steps to [=convert a
        value to a key=] with |key|. Rethrow any exceptions.

    2. If |r| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

    3. Let |key| be |r|.

9. Let |clone| be [=structured clone=] of |value|.
    Rethrow any exceptions.

10. If |store| uses [=in-line keys=], run these substeps:

    1. Let |kpk| be the result of running the steps to [=extract a
        key from a value using a key path=] with |clone| and
        |store|'s [=object-store/key path=]. Rethrow any
        exceptions.

    2. If |kpk| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

    3. If |kpk| is not failure, let |key| be |kpk|.

    4. Otherwise, if |store| does not have a [=key
        generator=], [=throw=] a "{{DataError}}" {{DOMException}}.

11. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=/object store handle=] as |source| and the
    [=steps for storing a record into an object store=] as
    |operation|, using |store|, the |clone| as |value|, |key|, and
    with the |no-overwrite flag| unset.

</div>

The <dfn method for=IDBObjectStore>add(|value|, |key|)</dfn> method,
when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. If |transaction| is a [=read-only transaction=],
    [=throw=] a "{{ReadOnlyError}}" {{DOMException}}.

6. If |store| uses [=in-line keys=] and |key| was given,
    [=throw=] a "{{DataError}}" {{DOMException}}.

7. If |store| uses [=out-of-line keys=] and has no [=key
    generator=] and |key| was not given, [=throw=] a
    "{{DataError}}" {{DOMException}}.

8. If |key| was given, run these substeps:

    1. Let |r| be the result of running the steps to [=convert a
        value to a key=] with |key|. Rethrow any exceptions.

    2. If |r| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

    3. Let |key| be |r|.

9. Let |clone| be [=structured clone=] of |value|. Rethrow any
    exceptions.

10. If |store| uses [=in-line keys=], run these substeps:

    1. Let |kpk| be the result of running the steps to [=extract a
        key from a value using a key path=] with |clone| and
        |store|'s [=object-store/key path=]. Rethrow any
        exceptions.

    2. If |kpk| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

    3. If |kpk| is not failure, let |key| be
        |kpk|.

    4. Otherwise, if |store| does not have a [=key
        generator=], [=throw=] a "{{DataError}}" {{DOMException}}.

11. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=/object store handle=] as |source| and the
    [=steps for storing a record into an object store=] as
    |operation|, using |store|, |clone| as |value|, |key|, and with
    the |no-overwrite flag| set.

</div>

The <dfn method for=IDBObjectStore>delete(|query|)</dfn> method, when
invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. If |transaction| is a [=read-only transaction=],
    [=throw=] a "{{ReadOnlyError}}" {{DOMException}}.

6. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query| and
    |null disallowed flag| set. Rethrow any exceptions.

7. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=/object store handle=] as |source| and
    the [=steps for deleting records from an object store=] as
    |operation|, using |store| and |range|.

</div>

The |query| parameter may be a [=/key=] or an
{{IDBKeyRange}} identifying the [=object-store/records=] keys to be
deleted.

<aside class=note>
  Unlike other methods which take keys or key ranges, this method does
  <strong>not</strong> allow null to be given as key. This is to
  reduce the risk that a small bug would clear a whole object store.
</aside>


The <dfn method for=IDBObjectStore>clear()</dfn> method, when invoked,
must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. If |transaction| is a [=read-only transaction=],
    [=throw=] a "{{ReadOnlyError}}" {{DOMException}}.

6. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=/object store handle=] as |source| and
    the [=steps for clearing an object store=] as
    |operation|, using |store|.


<div class=note>
  The following methods throw a "{{TransactionInactiveError}}" {{DOMException}} if called
  when the [=/transaction=] is not [=transaction/active=].

  <dl class=domintro>
    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBObjectStore/get()|get}}(<var>query</var>)
    </dt>
    <dd>
       Retrieves the [=/value=] of the first [=object-store/record=] matching the
       given [=/key=] or [=key range=] in |query|.

       If successful, |request|'s {{IDBRequest/result}} will be the
       [=/value=], or <code>undefined</code> if there was no matching
       [=object-store/record=].
    </dd>

    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBObjectStore/getKey()|getKey}}(<var>query</var>)
    </dt>
    <dd>
       Retrieves the [=/key=] of the first [=object-store/record=] matching the
       given [=/key=] or [=key range=] in |query|.

       If successful, |request|'s {{IDBRequest/result}} will be the
       [=/key=], or <code>undefined</code> if there was no matching
       [=object-store/record=].
    </dd>

    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBObjectStore/getAll()|getAll}}(<var>query</var> [, <var>count</var>])
    </dt>
    <dd>
       Retrieves the [=/values=] of the [=object-store/records=] matching the
       given [=/key=] or [=key range=] in |query| (up to |count| if given).

       If successful, |request|'s {{IDBRequest/result}} will
       be an [=Array=] of the [=/values=].
    </dd>

    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBObjectStore/getAllKeys()|getAllKeys}}(<var>query</var> [,
          <var>count</var>])
    </dt>
    <dd>
       Retrieves the [=/keys=] of [=object-store/records=] matching the
       given [=/key=] or [=key range=] in |query| (up to |count| if given).

       If successful, |request|'s {{IDBRequest/result}} will
       be an [=Array=] of the [=/keys=].
    </dd>

    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBObjectStore/count()|count}}(<var>query</var>)
    </dt>
    <dd>
       Retrieves the number of [=object-store/records=] matching the
       given [=/key=] or [=key range=] in |query|.

       If successful, |request|'s {{IDBRequest/result}} will be the count.
    </dd>
  </dl>
</div>

The <dfn method for=IDBObjectStore>get(|query|)</dfn> method, when
invoked, must run these steps:

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query| and
    |null disallowed flag| set. Rethrow any exceptions.

6. Run the [=steps for asynchronously executing a request=] and
      return the {{IDBRequest}} created by these steps. The steps
      are run with this [=/object store handle=] as
      |source| and the [=steps for retrieving a value from
      an object store=] as |operation|, using
      |store| and |range|.

</div>

The |query| parameter may be a [=/key=] or an
{{IDBKeyRange}} identifying the [=object-store/record=] to be retrieved. If a
range is specified, the method retrieves the first existing value in
that range.

<aside class=note>
  This method produces the same result if a record with the given key
  doesn't exist as when a record exists, but has <code>undefined</code> as value.
  If you need to tell the two situations apart, you can use
  {{IDBObjectStore/openCursor()}} with the same key. This will return
  a cursor with <code>undefined</code> as value if a record exists, or no cursor if
  no such record exists.
</aside>


The <dfn method for=IDBObjectStore>getKey(|query|)</dfn> method, when
invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query| and
    |null disallowed flag| set. Rethrow any exceptions.

6. Run the [=steps for asynchronously executing a request=] and
      return the {{IDBRequest}} created by these steps. The steps
      are run with this [=/object store handle=] as
      |source| and the [=steps for retrieving a key from an
      object store=] as |operation|, using |store|
      and |range|.

</div>

The |query| parameter may be a [=/key=] or an
{{IDBKeyRange}} identifying the [=object-store/record=] key to be
retrieved. If a range is specified, the method retrieves
the first existing key in that range.

<aside class=advisement>
  &#x1F6A7;
  The {{IDBObjectStore/getKey()}} method on {{IDBObjectStore}} is new
  in this edition.
  It will be supported in Firefox 51.
  &#x1F6A7;
</aside>


The <dfn method for=IDBObjectStore>getAll(|query|, |count|)</dfn>
method, when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query|.
    Rethrow any exceptions.

6. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=/object store handle=] as |source| and the
    [=steps for retrieving multiple values from an object store=]
    as |operation|, using |store|, |range|, and |count| if given.

</div>

The |query| parameter may be a [=/key=] or an {{IDBKeyRange}}
identifying the [=object-store/records=] to be retrieved. If null or not given,
an [=unbounded key range=] is used. If |count| is specified and
there are more than |count| records in range, only the first |count|
will be retrieved.

<aside class=advisement>
  &#x1F6A7;
  The {{IDBObjectStore/getAll()}} method is new in this edition.
  It is supported in Chrome 48 and Firefox 44.
  &#x1F6A7;
</aside>


The <dfn method for=IDBObjectStore>getAllKeys(|query|, |count|)</dfn>
method, when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query|.
    Rethrow any exceptions.

6. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=/object store handle=] as |source| and the
    [=steps for retrieving multiple keys from an object store=] as
    |operation|, using |store|, |range|, and |count| if given.

</div>

The |query| parameter may be a [=/key=] or an {{IDBKeyRange}}
identifying the [=object-store/records=] keys to be retrieved. If null or not
given, an [=unbounded key range=] is used. If |count| is specified
and there are more than |count| keys in range, only the first |count|
will be retrieved.

<aside class=advisement>
  &#x1F6A7;
  The {{IDBObjectStore/getAllKeys()}} method is new in this edition.
  It is supported in Chrome 48 and Firefox 44.
  &#x1F6A7;
</aside>


The <dfn method for=IDBObjectStore>count(|query|)</dfn> method, when
invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query|.
    Rethrow any exceptions.

6. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=/object store handle=] as |source| and the
    [=steps to count the records in a range=] as |operation|, with
    |source| and |range|.

</div>

The |query| parameter may be a [=/key=] or an {{IDBKeyRange}}
identifying the [=object-store/records=] keys to be counted. If null or not
given, an [=unbounded key range=] is used.

<div class=note>
  The following methods throw a "{{TransactionInactiveError}}" {{DOMException}} if called
  when the [=/transaction=] is not [=transaction/active=].

  <dl class=domintro>
    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBObjectStore/openCursor()|openCursor}}([<var>query</var>
              [, <var>direction</var> = "next"]])
    </dt>
    <dd>
       Opens a [=cursor=] over the [=object-store/records=] matching |query|,
       ordered by |direction|. If |query| is null, all [=object-store/records=] in
       |store| are matched.

       If successful, |request|'s {{IDBRequest/result}} will be an
       {{IDBCursorWithValue}} pointing at the first matching
       [=object-store/record=], or null if there were no matching [=object-store/records=].
    </dd>

    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBObjectStore/openKeyCursor()|openKeyCursor}}([<var>query</var>
              [, <var>direction</var> = "next"]])
    </dt>
    <dd>
       Opens a [=cursor=] with [=cursor/key only flag=] set over the
       [=object-store/records=] matching |query|, ordered by |direction|. If
       |query| is null, all [=object-store/records=] in |store| are matched.

       If successful, |request|'s {{IDBRequest/result}} will be an
       {{IDBCursor}} pointing at the first matching [=object-store/record=], or
       null if there were no matching [=object-store/records=].
    </dd>
  </dl>
</div>

The <dfn method for=IDBObjectStore>openCursor(|query|,
|direction|)</dfn> method, when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query|.
    Rethrow any exceptions.

6. Let |cursor| be a new [=cursor=] with
    [=cursor/transaction=] set to |transaction|, an undefined
    [=cursor/position=], [=cursor/direction=] set to |direction|, [=got value
    flag=] unset, and undefined [=cursor/key=] and
    [=cursor/value=]. The [=cursor/source=] of |cursor| is
    |store|. The [=cursor/range=] of |cursor| is |range|.

7. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=/object store handle=] as |source| and the
    [=steps for iterating a cursor=] with |cursor| as |operation|.

</div>

The |query| parameter may be a [=/key=] or an
{{IDBKeyRange}} to use as the [=cursor=]'s [=cursor/range=].
If null or not given, an [=unbounded key range=] is used.


The <dfn method for=IDBObjectStore>openKeyCursor(|query|,
|direction|)</dfn> method, when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query|.
    Rethrow any exceptions.

6. Let |cursor| be a new [=cursor=] with
    [=cursor/transaction=] set to
    |transaction|, an undefined [=cursor/position=],
    [=cursor/direction=] set to |direction|, [=got value
    flag=] unset, and undefined [=cursor/key=] and
    [=cursor/value=]. The
    [=cursor/source=] of |cursor| is
    |store|. The [=cursor/range=] of |cursor| is
    |range|. The [=key only flag=] of |cursor| is
    set.

7. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=/object store handle=] as |source| and
    the [=steps for iterating a cursor=] with |cursor| as
    |operation|.

</div>

The |query| parameter may be a [=/key=] or an
{{IDBKeyRange}} to use as the [=cursor=]'s [=cursor/range=]. If null
or not given, an [=unbounded key range=] is used.

<aside class=advisement>
  &#x1F6A7;
  The {{IDBObjectStore/openKeyCursor()}} method is new in this edition.
  It is supported in Chrome 48 and Firefox 44.
  &#x1F6A7;
</aside>

<div class=note>
  <dl class=domintro>
    <dt>
      <var>index</var> = <var>store</var> . index(<var>name</var>)
    </dt>
    <dd>
      Returns an {{IDBIndex}} for the [=/index=] named |name| in |store|.
    </dd>

    <dt>
      <var>index</var> = <var>store</var> .
          {{IDBObjectStore/createIndex()|createIndex}}(<var>name</var>,
              <var>keyPath</var> [, <var>options</var>])
    </dt>
    <dd>
      Creates a new [=/index=] in |store| with the given |name|,
      |keyPath| and |options| and returns a new {{IDBIndex}}. If the
      |keyPath| and |options| define constraints that cannot be
      satisfied with the data already in |store| the [=upgrade
      transaction=] will [=transaction/abort=] with
      a "{{ConstraintError}}" {{DOMException}}.

      Throws an "{{InvalidStateError}}" {{DOMException}} if not called within an [=upgrade
      transaction=].
    </dd>

    <dt>
      <var>store</var> . {{IDBObjectStore/deleteIndex()|deleteIndex}}(<var>name</var>)
    </dt>
    <dd>
      Deletes the [=/index=] in |store| with the given |name|.

      Throws an "{{InvalidStateError}}" {{DOMException}} if not called within an [=upgrade
      transaction=].
    </dd>

  </dl>
</div>

The <dfn method for=IDBObjectStore>createIndex(|name|, |keyPath|,
|options|)</dfn> method, when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |transaction| is not an [=upgrade transaction=],
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

4. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

5. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

6. If an [=/index=] [=index/named=]
    |name| already exists in |store|, [=throw=] a
    "{{ConstraintError}}" {{DOMException}}.

7. If |keyPath| is not a [=valid key path=], [=throw=]
    a "{{SyntaxError}}" {{DOMException}}.

8. Let |unique| be set if |options|'s
    {{IDBIndexParameters/unique}} member is true, and unset otherwise.

9. Let |multiEntry| be set if |options|'s
    {{IDBIndexParameters/multiEntry}} member is true, and unset otherwise.

10. If |keyPath| is a sequence and |multiEntry| is
    set, [=throw=] an "{{InvalidAccessError}}" {{DOMException}}.

11. Let |index| be a new [=/index=] in |store|.
    Set |index|'s [=index/name=] to
    |name| and [=index/key path=] to
    |keyPath|. If |unique| is set, set
    |index|'s [=unique flag=]. If |multiEntry| is
    set, set |index|'s [=multiEntry flag=].

12. Add |index| to this [=/object store handle=]'s [=index
      set=].

13. Return a new [=index handle=] associated with |index|
    and this [=/object store handle=].

</div>

This method creates and returns a new [=/index=] with the
given name in the [=/object store=]. Note that this method
must only be called from within an [=upgrade transaction=].

The index that is requested to be created can contain constraints on
the data allowed in the index's [=referenced=] object store, such
as requiring uniqueness of the values referenced by the index's
keyPath. If the [=referenced=] object store already contains data
which violates these constraints, this must not cause the
implementation of {{IDBObjectStore/createIndex()}} to throw an
exception or affect what it returns. The implementation must still
create and return an {{IDBIndex}} object, and the implementation must
[=queue a task=] to abort the [=upgrade transaction=] which was
used for the {{IDBObjectStore/createIndex()}} call.

This method synchronously modifies the {{IDBObjectStore/indexNames}}
property on the {{IDBObjectStore}} instance on which it was called.
Although this method does not return an {{IDBRequest}} object, the
index creation itself is processed as an asynchronous request within
the [=upgrade transaction=].

In some implementations it is possible for the implementation to
asynchronously run into problems creating the index after the
createIndex method has returned. For example in implementations where
metadata about the newly created index is queued up to be inserted
into the database asynchronously, or where the implementation might
need to ask the user for permission for quota reasons. Such
implementations must still create and return an {{IDBIndex}} object,
and once the implementation determines that creating the index has
failed, it must abort the transaction using the [=steps for aborting
a transaction=] using an appropriate error as |error|. For example
if creating the [=/index=] failed due to quota reasons,
a "{{QuotaExceededError}}" {{DOMException}} must be used as error and if the index can't be
created due to [=unique flag=] constraints, a "{{ConstraintError}}" {{DOMException}}
must be used as error.

<aside class=example>

  The asynchronous creation of indexes is observable in the following example:

  <pre class=lang-javascript>
    var request1 = objectStore.put({name: "betty"}, 1);
    var request2 = objectStore.put({name: "betty"}, 2);
    var index = objectStore.createIndex("by_name", "name", {unique: true});
  </pre>

  At the point where {{createIndex()}} called, neither of the
  [=requests=] have executed. When the second request executes, a
  duplicate name is created. Since the index creation is considered an
  asynchronous [=request=], the index's <a data-lt="unique
  flag">uniqueness constraint</a> does not cause the second
  [=request=] to fail. Instead, the [=/transaction=] will
  be [=transaction/aborted=] when the index is created and the constraint
  fails.
</aside>


The <dfn method for=IDBObjectStore>index(|name|)</dfn> method, when
invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| has [=transaction/finished=], [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

5. Let |index| be the [=/index=]
    [=index/named=] |name| in this [=/object
    store handle=]'s [=index set=] if one exists, or [=throw=]
    a "{{NotFoundError}}" {{DOMException}} otherwise.

6. Return an [=index handle=] associated with |index| and
    this [=/object store handle=].

</div>

<aside class=note>
  Each call to this method on the same {{IDBObjectStore}} instance
  with the same name returns the same {{IDBIndex}} instance.
</aside>

<aside class=note>
  The returned {{IDBIndex}} instance is specific to this
  {{IDBObjectStore}} instance. If this method is called on a
  different {{IDBObjectStore}} instance with the same name, a
  different {{IDBIndex}} instance is returned.
</aside>


The <dfn method for=IDBObjectStore>deleteIndex(|name|)</dfn> method,
when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=/object store handle=]'s
    [=object-store-handle/transaction=].

2. Let |store| be this [=/object store handle=]'s
    [=object-store-handle/object store=].

3. If |transaction| is not an [=upgrade transaction=],
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

4. If |store| has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

5. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

6. Let |index| be the [=/index=] [=index/named=] |name|
    in |store| if one exists, or [=throw=] a "{{NotFoundError}}" {{DOMException}}
    otherwise.

7. Remove |index| from this [=/object store handle=]'s
    [=index set=].

8. Destroy |index|.

</div>

This method destroys the [=/index=] with the given name in the
[=/object store=]. Note that this method must only be called from
within an [=upgrade transaction=].

This method synchronously modifies the {{IDBObjectStore/indexNames}}
property on the {{IDBObjectStore}} instance on which it was called.
Although this method does not return an {{IDBRequest}} object, the
index destruction itself is processed as an asynchronous request
within the [=upgrade transaction=].


<!-- ============================================================ -->
<h3 id=index-interface>The {{IDBIndex}} interface</h3>
<!-- ============================================================ -->

The {{IDBIndex}} interface represents an [=index handle=].


<pre class=idl>
[Exposed=(Window,Worker)]
interface IDBIndex {
           attribute DOMString      name;
  readonly attribute IDBObjectStore objectStore;
  readonly attribute any            keyPath;
  readonly attribute boolean        multiEntry;
  readonly attribute boolean        unique;

  IDBRequest get(any query);
  IDBRequest getKey(any query);
  IDBRequest getAll(optional any query,
                    [EnforceRange] optional unsigned long count);
  IDBRequest getAllKeys(optional any query,
                        [EnforceRange] optional unsigned long count);
  IDBRequest count(optional any query);

  IDBRequest openCursor(optional any query,
                        optional IDBCursorDirection direction = "next");
  IDBRequest openKeyCursor(optional any query,
                           optional IDBCursorDirection direction = "next");
};
</pre>

<div class=note>
  <dl class=domintro>
    <dt><var>index</var> . {{IDBIndex/name}}</dt>
    <dd>
      Returns the [=index/name=] of the index.
    </dd>
    <dt><var>index</var> . {{IDBIndex/name}} = <var>newName</var></dt>
    <dd>
      Updates the [=index/name=] of the store to |newName|.

      Throws an "{{InvalidStateError}}" {{DOMException}} if not called within an [=upgrade
      transaction=].
    </dd>
    <dt><var>index</var> . {{IDBIndex/objectStore}}</dt>
    <dd>
      Returns the {{IDBObjectStore}} the index belongs to.
    </dd>
    <dt><var>index</var> . keyPath</dt>
    <dd>
      Returns the [=/key path=] of the index.
    </dd>
    <dt><var>index</var> . multiEntry</dt>
    <dd>
      Returns true if the index's [=index/multiEntry flag=] is set.
    </dd>
    <dt><var>index</var> . unique</dt>
    <dd>
      Returns true if the index's [=index/unique flag=] is set.
    </dd>
  </dl>
</div>

The <dfn attribute for=IDBIndex>name</dfn> attribute's getter must
return this [=index handle=]'s [=index/name=].

<aside class=note>
  As long as the [=/transaction=] has not [=transaction/finished=],
  this is the same as the associated [=/index=]'s
  [=index/name=]. Once the [=/transaction=] has
  [=transaction/finished=], this attribute will not reflect changes made with a
  later [=upgrade transaction=].
</aside>


The {{IDBIndex/name}} attribute's setter must run these steps:

<div class=algorithm>

1. Let |name| be the given value.

2. Let |transaction| be this [=index handle=]'s
    [=index-handle/transaction=].

3. Let |index| be this [=index handle=]'s
    [=index-handle/index=].

4. If |transaction| is not an [=upgrade transaction=],
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

5. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

6. If |index| or |index|'s [=/object store=] has
    been deleted, [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

7. If |index|'s [=index/name=] is equal to
    |name|, terminate these steps.

8. If an [=/index=] [=index/named=]
    |name| already exists in |index|'s [=/object
    store=], [=throw=] a "{{ConstraintError}}" {{DOMException}}.

9. Set |index|'s [=index/name=] to
    |name|.

10. Set this [=index handle=]'s
    [=index-handle/name=] to |name|.

</div>

<aside class=advisement>
  &#x1F6A7;
  The {{IDBIndex/name}} attribute's setter is new in this edition.
  It will be supported in Firefox 51.
  &#x1F6A7;
</aside>


The <dfn attribute for=IDBIndex>objectStore</dfn> attribute's getter
must return this [=index handle=]'s [=index-handle/object
store handle=].

The <dfn attribute for=IDBIndex>keyPath</dfn> attribute's getter must
return this [=index handle=]'s [=index-handle/index=]'s
[=object-store/key path=].

The conversion is done following the normal [[!WEBIDL]] binding logic
for {{DOMString}} and [=sequence&lt;DOMString&gt;=] values, as
appropriate.

The returned value is not the same instance that was used when the
[=/index=] was created. However, if this attribute returns an
object (specifically an [=Array=]), it returns the same object
instance every time it is inspected. Changing the properties of the
object has no effect on the [=/index=].

The <dfn attribute for=IDBIndex>multiEntry</dfn> attribute's getter
must return true if this [=index handle=]'s
[=index-handle/index=]'s [=multiEntry flag=] is set, and false
otherwise.

The <dfn attribute for=IDBIndex>unique</dfn> attribute's getter must
return true if this [=index handle=]'s
[=index-handle/index=]'s [=unique flag=] is set, and false
otherwise.


<div class=note>
  The following methods throw an "{{TransactionInactiveError}}" {{DOMException}} if called
  when the [=/transaction=] is not [=transaction/active=].

  <dl class=domintro>
    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBIndex/get()|get}}(<var>query</var>)
    </dt>
    <dd>
       Retrieves the [=/value=] of the first [=object-store/record=] matching the
       given [=/key=] or [=key range=] in |query|.

       If successful, |request|'s {{IDBRequest/result}} will be the
       [=/value=], or <code>undefined</code> if there was no matching
       [=object-store/record=].
    </dd>

    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBIndex/getKey()|getKey}}(<var>query</var>)
    </dt>
    <dd>
       Retrieves the [=/key=] of the first [=object-store/record=] matching the
       given [=/key=] or [=key range=] in |query|.

       If successful, |request|'s {{IDBRequest/result}} will be the
       [=/key=], or <code>undefined</code> if there was no matching
       [=object-store/record=].
    </dd>

    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBIndex/getAll()|getAll}}(<var>query</var> [, <var>count</var>])
    </dt>
    <dd>
       Retrieves the [=/values=] of the [=object-store/records=] matching the given
       [=/key=] or [=key range=] in |query| (up to |count| if given).

       If successful, |request|'s {{IDBRequest/result}} will be an
       [=Array=] of the [=/values=].
    </dd>

    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBIndex/getAllKeys()|getAllKeys}}(<var>query</var> [,
          <var>count</var>])
    </dt>
    <dd>
       Retrieves the [=/keys=] of [=object-store/records=] matching the given
       [=/key=] or [=key range=] in |query| (up to |count| if given).

       If successful, |request|'s {{IDBRequest/result}} will be an
       [=Array=] of the [=/keys=].
    </dd>

    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBIndex/count()|count}}(<var>query</var>)
    </dt>
    <dd>
       Retrieves the number of [=object-store/records=] matching the given [=/key=]
       or [=key range=] in |query|.

       If successful, |request|'s {{IDBRequest/result}} will be the
       count.
    </dd>
  </dl>
</div>

The <dfn method for=IDBIndex>get(|query|)</dfn> method, when invoked,
must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=index handle=]'s
    [=index-handle/transaction=].

2. Let |index| be this [=index handle=]'s
    [=index-handle/index=].

3. If |index| or |index|'s [=/object store=] has
    been deleted, [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query| and
    |null disallowed flag| set. Rethrow any exceptions.

6. Run the [=steps for asynchronously executing a request=] and
      return the {{IDBRequest}} created by these steps. The steps
      are run with this [=index handle=] as |source| and
      the [=steps for retrieving a referenced value from an index=]
      as |operation|, using |index| and
      |range|.

</div>

The |query| parameter may be a [=/key=] or an
{{IDBKeyRange}} identifying the [=object-store/record=] to be retrieved. If a
range is specified, the method retrieves the first existing record in
that range.


<aside class=note>
  This method produces the same result if a record with the given key
  doesn't exist as when a record exists, but has <code>undefined</code> as value.
  If you need to tell the two situations apart, you can use
  {{IDBIndex/openCursor()}} with the same key. This will return a
  cursor with <code>undefined</code> as value if a record exists, or no cursor if
  no such record exists.
</aside>


The <dfn method for=IDBIndex>getKey(|query|)</dfn> method, when
invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=index handle=]'s
    [=index-handle/transaction=].

2. Let |index| be this [=index handle=]'s
    [=index-handle/index=].

3. If |index| or |index|'s [=/object store=] has been deleted,
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to [=convert a
    value to a key range=] with |query| and |null disallowed flag|
    set. Rethrow any exceptions.

6. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=index handle=] as |source| and the [=steps for
    retrieving a value from an index=] as |operation|, using |index|
    and |range|.

</div>

The |query| parameter may be a [=/key=] or an
{{IDBKeyRange}} identifying the [=object-store/record=] key to be retrieved.
If a range is specified, the method retrieves the first existing key
in that range.


The <dfn method for=IDBIndex>getAll(|query|, |count|)</dfn> method,
when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=index handle=]'s
    [=index-handle/transaction=].

2. Let |index| be this [=index handle=]'s
    [=index-handle/index=].

3. If |index| or |index|'s [=/object store=] has
    been deleted, [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query|.
    Rethrow any exceptions.

6. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=index handle=] as |source| and the [=steps for
    retrieving multiple referenced values from an index=] as
    |operation|, using |index|, |range|, and |count| if given.

</div>

The |query| parameter may be a [=/key=] or an {{IDBKeyRange}}
identifying the [=object-store/records=] to be retrieved. If null or not given,
an [=unbounded key range=] is used. If |count| is specified and
there are more than |count| records in range, only the first |count|
will be retrieved.

<aside class=advisement>
  &#x1F6A7;
  The {{IDBIndex/getAll()}} method is new in this edition.
  It is supported in Chrome 48 and Firefox 44.
  &#x1F6A7;
</aside>


The <dfn method for=IDBIndex>getAllKeys(|query|, |count|)</dfn>
method, when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=index handle=]'s
    [=index-handle/transaction=].

2. Let |index| be this [=index handle=]'s
    [=index-handle/index=].

3. If |index| or |index|'s [=/object store=] has
    been deleted, [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query|.
    Rethrow any exceptions.

6. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=index handle=] as |source| and the [=steps for
    retrieving multiple values from an index=] as |operation|, using
    |index|, |range|, and |count| if given.

</div>

The |query| parameter may be a [=/key=] or an {{IDBKeyRange}}
identifying the [=object-store/records=] keys to be retrieved. If null or not
given, an [=unbounded key range=] is used. If |count| is specified
and there are more than |count| keys in range, only the first |count|
will be retrieved.

<aside class=advisement>
  &#x1F6A7;
  The {{IDBIndex/getAllKeys()}} method is new in this edition.
  It is supported in Chrome 48 and Firefox 44.
  &#x1F6A7;
</aside>


The <dfn method for=IDBIndex>count(|query|)</dfn> method, when
invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=index handle=]'s
    [=index-handle/transaction=].

2. Let |index| be this [=index handle=]'s
    [=index-handle/index=].

3. If |index| or |index|'s [=/object store=] has
    been deleted, [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query|.
    Rethrow any exceptions.

6. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=index handle=] as |source| and the [=steps to
    count the records in a range=] as |operation|, with
    [=/index=] as |source| and |range|.

</div>

The |query| parameter may be a [=/key=] or an {{IDBKeyRange}}
identifying the [=object-store/records=] keys to be counted. If null or not
given, an [=unbounded key range=] is used.

<div class=note>
  The following methods throw an "{{TransactionInactiveError}}" {{DOMException}} if called
  when the [=/transaction=] is not [=transaction/active=].

  <dl class=domintro>
    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBIndex/openCursor()|openCursor}}([<var>query</var>
              [, <var>direction</var> = "next"]])
    </dt>
    <dd>
       Opens a [=cursor=] over the [=object-store/records=] matching |query|,
       ordered by |direction|. If |query| is null, all [=object-store/records=] in
       |index| are matched.

       If successful, |request|'s {{IDBRequest/result}} will be an
       {{IDBCursorWithValue}}, or null if there were no matching
       [=object-store/records=].
    </dd>

    <dt>
      <var>request</var> = <var>store</var> .
          {{IDBIndex/openKeyCursor()|openKeyCursor}}([<var>query</var>
              [, <var>direction</var> = "next"]])
    </dt>
    <dd>
       Opens a [=cursor=] with [=cursor/key only flag=] set over the
       [=object-store/records=] matching |query|, ordered by |direction|. If
       |query| is null, all [=object-store/records=] in |index| are matched.

       If successful, |request|'s {{IDBRequest/result}} will be an
       {{IDBCursor}}, or null if there were no matching [=object-store/records=].
    </dd>
  </dl>
</div>

The <dfn method for=IDBIndex>openCursor(|query|, |direction|)</dfn>
method, when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=index handle=]'s
    [=index-handle/transaction=].

2. Let |index| be this [=index handle=]'s
    [=index-handle/index=].

3. If |index| or |index|'s [=/object store=] has been deleted,
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query|.
    Rethrow any exceptions.

6. Let |cursor| be a new [=cursor=] with
    [=cursor/transaction=] set to |transaction|, an undefined
    [=cursor/position=], [=cursor/direction=] set to |direction|, [=got value
    flag=] unset, and undefined [=cursor/key=] and
    [=cursor/value=]. The [=cursor/source=] of |cursor| is
    |index|. The [=cursor/range=] of |cursor| is |range|.

7. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=index handle=] as |source| and the [=steps for
    iterating a cursor=] with |cursor| as |operation|.

</div>

The |query| parameter may be a [=/key=] or an
{{IDBKeyRange}} to use as the [=cursor=]'s [=cursor/range=]. If null
or not given, an [=unbounded key range=] is used.


The <dfn method for=IDBIndex>openKeyCursor(|query|, |direction|)</dfn>
method, when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=index handle=]'s
    [=index-handle/transaction=].

2. Let |index| be this [=index handle=]'s
    [=index-handle/index=].

3. If |index| or |index|'s [=/object store=] has
    been deleted, [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

4. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

5. Let |range| be the result of running the steps to
    [=convert a value to a key range=] with |query|.
    Rethrow any exceptions.

7. Let |cursor| be a new [=cursor=] with
    [=cursor/transaction=] set to |transaction|, an undefined
    [=cursor/position=], [=cursor/direction=] set to |direction|, [=got value
    flag=] unset, and undefined [=cursor/key=] and
    [=cursor/value=]. The [=cursor/source=] of |cursor| is
    |index|. The [=cursor/range=] of |cursor| is |range|. The [=key only
    flag=] of |cursor| is set.

8. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=index handle=] as |source| and the
    [=steps for iterating a cursor=] with |cursor| as
    |operation|.

</div>

The |query| parameter may be a [=/key=] or an
{{IDBKeyRange}} to use as the [=cursor=]'s [=cursor/range=]. If null
or not given, an [=unbounded key range=] is used.


<!-- ============================================================ -->
<h3 id=keyrange>The {{IDBKeyRange}} interface</h3>
<!-- ============================================================ -->

The {{IDBKeyRange}} interface represents a
[=key range=].

<pre class=idl>
[Exposed=(Window,Worker)]
interface IDBKeyRange {
  readonly attribute any     lower;
  readonly attribute any     upper;
  readonly attribute boolean lowerOpen;
  readonly attribute boolean upperOpen;

  // Static construction methods:
  static IDBKeyRange only(any value);
  static IDBKeyRange lowerBound(any lower, optional boolean open = false);
  static IDBKeyRange upperBound(any upper, optional boolean open = false);
  static IDBKeyRange bound(any lower,
                           any upper,
                           optional boolean lowerOpen = false,
                           optional boolean upperOpen = false);

  boolean includes(any key);
};
</pre>

<div class=note>
  <dl class=domintro>
    <dt><var>range</var> . {{IDBKeyRange/lower}}</dt>
    <dd>
      Returns [=lower bound=], or <code>undefined</code> if none.
    </dd>
    <dt><var>range</var> . {{IDBKeyRange/upper}}</dt>
    <dd>
      Returns [=upper bound=], or <code>undefined</code> if none.
    </dd>

    <dt><var>range</var> . {{IDBKeyRange/lowerOpen}}</dt>
    <dd>
      Returns true if the [=lower open flag=] is set, and false otherwise.
    </dd>
    <dt><var>range</var> . {{IDBKeyRange/upperOpen}}</dt>
    <dd>
      Returns true if the [=upper open flag=] is set, and false otherwise.
    </dd>
  </dt>
</div>

The <dfn attribute for=IDBKeyRange>lower</dfn> attribute's getter must
return result of running the steps to [=convert a key to a value=]
with the [=lower bound=] if it is not null, or undefined otherwise.

The <dfn attribute for=IDBKeyRange>upper</dfn> attribute's getter must
return the result of running the steps to [=convert a key to a
value=] with the [=upper bound=] if it is not null, or undefined
otherwise.

The <dfn attribute for=IDBKeyRange>lowerOpen</dfn> attribute's getter
must return true if the [=lower open flag=] is set, and false
otherwise.

The <dfn attribute for=IDBKeyRange>upperOpen</dfn> attribute's getter
must return true if the [=upper open flag=] is set, and false
otherwise.

<div class=note>
  <dl class=domintro>
    <dt><var>range</var> = {{IDBKeyRange}} .
        {{IDBKeyRange/only()|only}}(<var>key</var>)</dt>
    <dd>
      Returns a new {{IDBKeyRange}} spanning only |key|.
    </dd>
    <dt><var>range</var> = {{IDBKeyRange}} .
        {{IDBKeyRange/lowerBound()|lowerBound}}(<var>key</var> [, <var>open</var> = false])</dt>
    <dd>
      Returns a new {{IDBKeyRange}} starting at |key| with no
      upper bound. If |open| is true, |key| is not included in the
      range.
    </dd>
    <dt><var>range</var> = {{IDBKeyRange}} .
        {{IDBKeyRange/upperBound()|upperBound}}(<var>key</var> [, <var>open</var> = false])</dt>
    <dd>
      Returns a new {{IDBKeyRange}} with no lower bound and ending at
      |key|. If |open| is true, |key| is not included in the range.
    </dd>
    <dt><var>range</var> = {{IDBKeyRange}} .
        {{IDBKeyRange/bound()|bound}}(<var>lower</var>, <var>upper</var>
            [, <var>lowerOpen</var> = false
            [, <var>upperOpen</var> = false]])</dt>
    <dd>
      Returns a new {{IDBKeyRange}} spanning from |lower| to |upper|.
      If |lowerOpen| is true, |lower| is not included in the range.
      If |upperOpen| is true, |upper| is not included in the range.
    </dd>
  </dl>
</div>

The <dfn method for=IDBKeyRange>only(|value|)</dfn> method, when
invoked, must run these steps:

<div class=algorithm>

1. Let |key| be the result of running the steps to [=convert
    a value to a key=] with |value|. Rethrow any exceptions.

2. If |key| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

3. Create and return a new [=key range=] [=containing only=]
    |key|.

</div>

The <dfn method for=IDBKeyRange>lowerBound(|lower|, |lowerOpen|)</dfn>
method, when invoked, must run these steps:

<div class=algorithm>

1. Let |lowerKey| be the result of running the steps to [=convert a
    value to a key=] with |lower|. Rethrow any exceptions.

2. If |lowerKey| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

3. Create and return a new [=key range=] with [=lower bound=]
    set to |lowerKey|, [=lower open flag=] set if |lowerOpen| is
    true, [=upper bound=] set to null and [=upper open flag=]
    set.

</div>

The <dfn method for=IDBKeyRange>upperBound(|upper|, |upperOpen|)</dfn>
method, when invoked, must run these steps:

<div class=algorithm>

1. Let |upperKey| be the result of running the steps to [=convert a
    value to a key=] with |upper|. Rethrow any exceptions.

2. If |upperKey| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

3. Create and return a new [=key range=] with [=lower bound=]
    set to null, [=lower open flag=] set, [=upper bound=] set if
    |upperKey|, and [=upper open flag=] set to |upperOpen|.

</div>

The <dfn method for=IDBKeyRange>bound(|lower|, |upper|, |lowerOpen|,
|upperOpen|)</dfn> method, when invoked, must run these steps:

<div class=algorithm>

1. Let |lowerKey| be the result of running the steps to [=convert a
    value to a key=] with |lower|. Rethrow any exceptions.

2. If |lowerKey| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

3. Let |upperKey| be the result of running the steps to [=convert a
    value to a key=] with |upper|. Rethrow any exceptions.

4. If |upperKey| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

5. If |lowerKey| is [=greater than=] |upperKey|, [=throw=] a
    "{{DataError}}" {{DOMException}}.

6. Create and return a new [=key range=] with [=lower bound=]
    set to |lowerKey|, [=lower open flag=] set if |lowerOpen| is
    true, [=upper bound=] set to |upperKey| and [=upper open
    flag=] set if |upperOpen| is true.

</div>

<div class=note>
  <dl class=domintro>
    <dt><var>range</var> .
        {{IDBKeyRange/includes()|includes}}(<var>key</var>)</dt>
    <dd>
      Returns true if |key| is included in the range, and false otherwise.
    </dd>
  </dl>
</div>

The <dfn method for=IDBKeyRange>includes(|key|)</dfn> method, when
invoked, must run these steps:

<div class=algorithm>

1. Let |k| be the result of running the steps to [=convert a
    value to a key=] with |key|. Rethrow any exceptions.

2. If |k| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

3. Return true if |k| is [=in=]
    this range, and false otherwise.

</div>

<aside class=advisement>
  &#x1F6A7;
  The {{IDBKeyRange/includes()}} method is new in this edition.
  It is supported in Chrome 52 and Firefox 47.
  &#x1F6A7;
</aside>


<!-- ============================================================ -->
<h3 id=cursor-interface>The {{IDBCursor}} interface</h3>
<!-- ============================================================ -->

[=Cursor=] objects implement the {{IDBCursor}} interface. There
is only ever one {{IDBCursor}} instance representing a given
[=cursor=]. There is no limit on how many cursors can be used at
the same time.


<pre class=idl>
[Exposed=(Window,Worker)]
interface IDBCursor {
  readonly attribute (IDBObjectStore or IDBIndex) source;
  readonly attribute IDBCursorDirection           direction;
  readonly attribute any                          key;
  readonly attribute any                          primaryKey;

  void advance([EnforceRange] unsigned long count);
  void continue(optional any key);
  void continuePrimaryKey(any key, any primaryKey);

  IDBRequest update(any value);
  IDBRequest delete();
};

enum IDBCursorDirection {
  "next",
  "nextunique",
  "prev",
  "prevunique"
};
</pre>


<div class=note>
  <dl class=domintro>
    <dt><var>cursor</var> . {{IDBCursor/source}}</dt>
    <dd>
      Returns the {{IDBObjectStore}} or {{IDBIndex}} the cursor was opened from.
    </dd>
    <dt><var>range</var> . {{IDBCursor/direction}}</dt>
    <dd>
      Returns the [=cursor/direction=]
      ({{"next"}}, {{"nextunique"}}, {{"prev"}} or {{"prevunique"}})
      of the cursor.
    </dd>
    <dt><var>cursor</var> . {{IDBCursor/key}}
    <dd>
      Returns the [=cursor/key=] of the cursor.
      Throws a "{{InvalidStateError}}" {{DOMException}} if the cursor is advancing or is finished.
    </dd>
    <dt><var>cursor</var> . {{IDBCursor/primaryKey}}
    <dd>
      Returns the [=cursor/effective key=] of the cursor.
      Throws a "{{InvalidStateError}}" {{DOMException}} if the cursor is advancing or is finished.
    </dd>
  </dl>
</div>


The <dfn attribute for=IDBCursor>source</dfn> attribute's getter must
return the [=cursor/source=] of this [=cursor=]. This
attribute never returns null or throws an exception, even if the
cursor is currently being iterated, has iterated past its end, or its
[=/transaction=] is not [=transaction/active=].

The <dfn attribute for=IDBCursor>direction</dfn> attribute's getter
must return the [=cursor/direction=] of the [=cursor=].

The <dfn attribute for=IDBCursor>key</dfn> attribute's getter must
return the result of running the steps to [=convert a key to a
value=] with the cursor's current [=cursor/key=]. Note that
if this property returns an object (e.g. a [=Date=] or
[=Array=]), it returns the same object instance every time it is
inspected, until the cursor's [=cursor/key=] is changed. This
means that if the object is modified, those modifications will be seen
by anyone inspecting the value of the cursor. However modifying such
an object does not modify the contents of the database.

The <dfn attribute for=IDBCursor>primaryKey</dfn> attribute's getter
must return the result of running the steps to [=convert a key to a
value=] with the cursor's current [=effective key=]. Note that if
this property returns an object (e.g. a [=Date=] or [=Array=]),
it returns the same object instance every time it is inspected, until
the cursor's [=effective key=] is changed. This means that if the
object is modified, those modifications will be seen by anyone
inspecting the value of the cursor. However modifying such an object
does not modify the contents of the database.

<div class=note>
  The following methods advance a [=cursor=]. Once the cursor has
  advanced, a <code>success</code> event will be fired at the
  same {{IDBRequest}} returned when the cursor was opened. The
  {{IDBRequest/result}} will be the same cursor if a [=object-store/record=] was
  in range, or <code>undefined</code> otherwise.

  If called while the cursor is already advancing, an "{{InvalidStateError}}" {{DOMException}}
  will be thrown.

  The following methods throw a "{{TransactionInactiveError}}" {{DOMException}} if called
  when the [=/transaction=] is not [=transaction/active=].

  <dl class=domintro>
    <dt><var>cursor</var> . {{IDBCursor/advance()|advance}}(<var>count</var>)</dt>
    <dd>
      Advances the cursor through the next |count| [=object-store/records=] in
      range.
    </dd>

    <dt><var>cursor</var> . {{IDBCursor/continue()|continue}}()</dt>
    <dd>
      Advances the cursor to the next [=object-store/record=] in range.
    </dd>

    <dt><var>cursor</var> . {{IDBCursor/continue()|continue}}(<var>key</var>)</dt>
    <dd>
      Advances the cursor to the next [=object-store/record=] in range matching or
      after |key|.
    </dd>

    <dt><var>cursor</var> .
        {{IDBCursor/continuePrimaryKey()|continuePrimaryKey}}(<var>key</var>,
        <var>primaryKey</var>)</dt>
    <dd>
      Advances the cursor to the next [=object-store/record=] in range matching
      or after |key| and |primaryKey|. Throws an "{{InvalidAccessError}}" {{DOMException}}
      if the [=cursor/source=] is not an [=/index=].
    </dd>
  </dl>
</div>



The <dfn method for=IDBCursor>advance(|count|)</dfn> method, when
invoked, must run these steps:

<div class=algorithm>

1. If |count| is 0 (zero), [=throw=] a [=TypeError=].

2. Let |transaction| be this [=cursor=]'s
    [=cursor/transaction=].

3. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

4. If the cursor's [=cursor/source=] or [=effective object
    store=] has been deleted, [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

5. If this cursor's [=got value flag=] is unset, indicating that
    the cursor is being iterated or has iterated past its end,
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

7. Unset the [=got value flag=] on the cursor.

8. Let |request| be the [=request=] created when this
    [=cursor=] was created.

9. Unset the [=request/done flag=] on |request|.

10. Run the [=steps for asynchronously executing a request=] with
    the cursor's [=cursor/source=] as |source| and the [=steps
    for iterating a cursor=] with this [=cursor=] and |count|,
    and |request|.

</div>

<aside class=note>
  Calling this method more than once before new cursor data has been
  loaded - for example, calling {{advance()}} twice from the
  same onsuccess handler - results in an "{{InvalidStateError}}" {{DOMException}}
  being thrown on the second call because the cursor's
  [=got value flag=] has been unset.
</aside>


The <dfn method for=IDBCursor>continue(|key|)</dfn> method, when
invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=cursor=]'s
    [=cursor/transaction=].

2. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

3. If the cursor's [=cursor/source=] or
    [=effective object store=] has been deleted, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

4. If this cursor's [=got value flag=] is unset, indicating that
    the cursor is being iterated or has iterated past its end,
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

5. If |key| is given, run these substeps:

    1. Let |r| be the result of running the steps to [=convert a
        value to a key=] with |key|. Rethrow any exceptions.

    2. If |r| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

    3. Let |key| be |r|.

    4. If |key| is [=less than=] or [=equal to=] this cursor's
        [=cursor/position=] and this cursor's [=cursor/direction=] is
        {{"next"}} or {{"nextunique"}}, [=throw=] a "{{DataError}}" {{DOMException}}.

    5. If |key| is [=greater than=] or [=equal to=] this
        cursor's [=cursor/position=] and this cursor's [=cursor/direction=] is
        {{"prev"}} or {{"prevunique"}}, [=throw=] a "{{DataError}}" {{DOMException}}.

6. Unset the [=got value flag=] on the cursor.

7. Let |request| be the [=request=] created when this
    [=cursor=] was created.

8. Unset the [=request/done flag=] on |request|.

9. Run the [=steps for asynchronously executing a request=] with
    the cursor's [=cursor/source=] as |source| and the [=steps
    for iterating a cursor=] with this [=cursor=] and |key| (if
    given), and |request|.

</div>

<aside class=note>
  Calling this method more than once before new cursor data has been
  loaded - for example, calling {{continue()}} twice from the
  same onsuccess handler - results in an "{{InvalidStateError}}" {{DOMException}}
  being thrown on the second call because the cursor's
  [=got value flag=] has been unset.
</aside>


The <dfn method for=IDBCursor>continuePrimaryKey(|key|,
|primaryKey|)</dfn> method, when invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=cursor=]'s
    [=cursor/transaction=].

2. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

3. If the cursor's [=cursor/source=] or [=effective object
    store=] has been deleted, [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

4. If this cursor's [=cursor/source=] is not an
    [=/index=] [=throw=] an "{{InvalidAccessError}}" {{DOMException}}.

5. If this cursor's [=cursor/direction=] is not {{"next"}} or {{"prev"}},
    [=throw=] an "{{InvalidAccessError}}" {{DOMException}}.

6. If this cursor's [=got value flag=] is unset, indicating that
    the cursor is being iterated or has iterated past its end,
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

7. Let |r| be the result of running the steps to [=convert a value to
    a key=] with |key|. Rethrow any exceptions.

8. If |r| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

9. Let |key| be |r|.

10. Let |r| be the result of running the steps to [=convert a value
     to a key=] with |primaryKey|. Rethrow any exceptions.

11. If |r| is invalid, [=throw=] a "{{DataError}}" {{DOMException}}.

12. Let |primaryKey| be |r|.

13. If |key| is [=less than=] this cursor's
    [=cursor/position=] and this cursor's [=cursor/direction=] is {{"next"}},
    [=throw=] a "{{DataError}}" {{DOMException}}.

14. If |key| is [=greater than=] this cursor's
    [=cursor/position=] and this cursor's [=cursor/direction=] is {{"prev"}},
    [=throw=] a "{{DataError}}" {{DOMException}}.

15. If |key| is [=equal to=] this cursor's [=cursor/position=] and
    |primaryKey| is [=less than=] or [=equal to=] this cursor's
    [=object store position=] and this cursor's [=cursor/direction=] is
    {{"next"}}, [=throw=] a "{{DataError}}" {{DOMException}}.

16. If |key| is [=equal to=] this cursor's [=cursor/position=] and
    |primaryKey| is [=greater than=] or [=equal to=] this
    cursor's [=object store position=] and this cursor's
    [=cursor/direction=] is {{"prev"}}, [=throw=] a
    "{{DataError}}" {{DOMException}}.

17. Unset the [=got value flag=] on the cursor.

18. Let |request| be the [=request=] created when this
    [=cursor=] was created.

19. Unset the [=request/done flag=] on |request|.

20. Run the [=steps for asynchronously executing a request=] with
    the cursor's [=cursor/source=] as |source| and the [=steps
    for iterating a cursor=] with this [=cursor=], |key|,
    |primaryKey|, and |request|.

</div>

<aside class=advisement>
  &#x1F6A7;
  The {{IDBCursor/continuePrimaryKey()}} method is new in this edition.
  It will be supported in Firefox 51.
  &#x1F6A7;
</aside>

<aside class=note>
  Calling this method more than once before new cursor data has been
  loaded - for example, calling {{continuePrimaryKey()}} twice from
  the same onsuccess handler - results in an "{{InvalidStateError}}" {{DOMException}}
  being thrown on the second call because the cursor's [=got value
  flag=] has been unset.
</aside>



<div class=note>
  The following methods throw a "{{ReadOnlyError}}" {{DOMException}} if called within a
  [=read-only transaction=], and a "{{TransactionInactiveError}}" {{DOMException}} if
  called when the [=/transaction=] is not [=transaction/active=].

  <dl class=domintro>
    <dt><var>request</var> = <var>cursor</var> .
        {{IDBCursor/update()|update}}(<var>value</var>)</dt>
    <dd>
      Updated the [=object-store/record=] pointed at by the cursor with a new value.

      Throws a "{{DataError}}" {{DOMException}} if the [=cursor/effective object store=]
      uses [=in-line keys=] and the [=/key=] would have changed.

      If successful, |request|'s {{IDBRequest/result}} will be the
      [=object-store/record=]'s [=/key=].
    </dd>

    <dt><var>request</var> = <var>cursor</var> .
        {{IDBCursor/delete()|delete}}()</dt>
    <dd>
      Delete the [=object-store/record=] pointed at by the cursor with a new value.

      If successful, |request|'s {{IDBRequest/result}} will be
      <code>undefined</code>.
    </dd>
  </dl>
</div>

The <dfn method for=IDBCursor>update(|value|)</dfn> method, when
invoked, must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=cursor=]'s
    [=cursor/transaction=].

2. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

3. If |transaction| is a [=read-only transaction=], [=throw=] a
    "{{ReadOnlyError}}" {{DOMException}}.

4. If the cursor's [=cursor/source=] or [=effective object
    store=] has been deleted, [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

5. If this cursor's [=got value flag=] is unset, indicating that
    the cursor is being iterated or has iterated past its end,
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

6. If this cursor's [=key only flag=] is set, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

7. Let |clone| be [=structured clone=] of |value|. Rethrow any
    exceptions.

8. If the [=effective object store=] of this cursor uses [=in-line
    keys=], run these substeps:

    1. Let |kpk| be the result of running the steps to
        [=extract a key from a value using a key path=] with
        |clone| and the [=object-store/key
        path=] of the [=effective object store=].
        Rethrow any exceptions.

    2. If |kpk| is failure, invalid, or not [=equal to=]
        the cursor's [=effective key=], [=throw=] a
        "{{DataError}}" {{DOMException}}.

9. Run [=steps for asynchronously executing a request=] and return
    the {{IDBRequest}} created by these steps. The steps are run with
    this [=cursor=] as |source| and the [=steps for storing a
    record into an object store=] as |operation|, using this
    cursor's [=effective object store=] as |store|, the |clone| as
    |value|, this cursor's [=effective key=] as |key|, and with the
    |no-overwrite flag| unset.

</div>

<aside class=note>
  A result of running the [=steps for storing a record into an object
  store=] is that if the record has been deleted since the cursor
  moved to it, a new record will be created.
</aside>


The <dfn method for=IDBCursor>delete()</dfn> method, when invoked,
must run these steps:

<div class=algorithm>

1. Let |transaction| be this [=cursor=]'s
    [=cursor/transaction=].

2. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

3. If |transaction| is a [=read-only transaction=], [=throw=] a
    "{{ReadOnlyError}}" {{DOMException}}.

4. If the cursor's [=cursor/source=] or [=effective object
    store=] has been deleted, [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

5. If this cursor's [=got value flag=] is unset, indicating that
    the cursor is being iterated or has iterated past its end,
    [=throw=] an "{{InvalidStateError}}" {{DOMException}}.

6. If this cursor's [=key only flag=] is set, [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

7. Run the [=steps for asynchronously executing a request=] and
    return the {{IDBRequest}} created by these steps. The steps are
    run with this [=cursor=] as |source| and the [=steps for
    deleting records from an object store=] as |operation|, using
    this cursor's [=effective object store=] and [=effective
    key=] as |store| and |key| respectively.

</div>

A [=cursor=] that has the [=key only flag=] unset implements the
{{IDBCursorWithValue}} interface as well.


<pre class=idl>
[Exposed=(Window,Worker)]
interface IDBCursorWithValue : IDBCursor {
  readonly attribute any value;
};
</pre>

<div class=note>
  <dl class=domintro>
    <dt><var>cursor</var> . {{IDBCursorWithValue/value}}</dt>
    <dd>
      Returns the [=cursor=]'s current [=cursor/value=].
    </dd>
  </dl>
</div>


The <dfn attribute for=IDBCursorWithValue>value</dfn> attribute's
getter must return the cursor's current [=cursor/value=]. Note
that if this property returns an object, it returns the same object
instance every time it is inspected, until the cursor's
[=cursor/value=] is changed. This means that if the object is
modified, those modifications will be seen by anyone inspecting the
value of the cursor. However modifying such an object does not modify
the contents of the database.


<!-- ============================================================ -->
<h3 id=transaction>The {{IDBTransaction}} interface</h3>
<!-- ============================================================ -->

[=/transaction=] objects implement the following interface:

<pre class=idl>
[Exposed=(Window,Worker)]
interface IDBTransaction : EventTarget {
  readonly attribute DOMStringList      objectStoreNames;
  readonly attribute IDBTransactionMode mode;
  readonly attribute IDBDatabase        db;
  readonly attribute DOMException       error;

  IDBObjectStore objectStore(DOMString name);
  void           abort();

  // Event handlers:
  attribute EventHandler onabort;
  attribute EventHandler oncomplete;
  attribute EventHandler onerror;
};

enum IDBTransactionMode {
  "readonly",
  "readwrite",
  "versionchange"
};
</pre>

<div class=note>
  <dl class=domintro>
    <dt><var>transaction</var> . {{IDBTransaction/objectStoreNames}}</dt>
    <dd>
      Returns a list of the names of [=/object stores=] in the
      transaction's [=transaction/scope=]. For an [=upgrade transaction=]
      this is all object stores in the [=database=].
    </dd>
    <dt><var>transaction</var> . {{IDBTransaction/mode}}</dt>
    <dd>
      Returns the [=transaction/mode=] the transaction was created with
      ({{"readonly"}} or {{"readwrite"}}), or {{"versionchange"}} for
      an [=upgrade transaction=].
    </dd>
    <dt><var>transaction</var> . {{IDBTransaction/db}}</dt>
    <dd>
      Returns the transaction's [=transaction/connection=].
    </dd>
    <dt><var>transaction</var> . {{IDBTransaction/error}}</dt>
    <dd>
      If the transaction was [=transaction/aborted=], returns the
      error (a {{DOMException}}) providing the reason.
    </dd>
  </dl>
</div>


The <dfn attribute for=IDBTransaction>objectStoreNames</dfn>
attribute's getter must run the following steps:

<div class=algorithm>

1. If this [=/transaction=] is an [=upgrade transaction=],
    return a [=sorted list=] of the [=object-store/names=]
    of the [=/object stores=] in this
    [=/transaction=]'s [=/connection=]'s [=object store
    set=].

2. Otherwise, return a [=sorted list=] of the
    [=object-store/names=] of the [=/object stores=] in
    this [=/transaction=]'s [=transaction/scope=].

</div>

<aside class=advisement>
  &#x1F6A7;
  The {{IDBTransaction/objectStoreNames}} attribute is new in this edition.
  It is supported in Chrome 48 and Firefox 44.
  &#x1F6A7;
</aside>

<aside class=note>
  The contents of each list returned by this attribute does not
  change, but subsequent calls to this attribute during an [=upgrade
  transaction=] may return lists with different contents as
  [=/object stores=] are created and deleted.
</aside>

The <dfn attribute for=IDBTransaction>mode</dfn> attribute's getter
must return the [=transaction/mode=] of the [=/transaction=].

The <dfn attribute for=IDBTransaction>db</dfn> attribute's getter must
return the [=database=] [=/connection=] of which this [=/transaction=]
is a part.

The <dfn attribute for=IDBTransaction>error</dfn> attribute's getter
must return this [=/transaction=]'s [=transaction/error=], or null if
none.

<aside class=note>
  If this [=/transaction=] was aborted due to a failed
  [=request=], this will be the same as the [=request=]'s
  [=request/error=]. If this [=/transaction=] was aborted
  due to an uncaught exception in an event handler, the error will be
  a "{{AbortError}}" {{DOMException}}. If the [=/transaction=] was aborted due to
  an error while committing, it will reflect the reason for the
  failure (e.g. "{{QuotaExceededError}}", "{{ConstraintError}}", or
  "{{UnknownError}}" {{DOMException}}).
</aside>

<div class=note>
  <dl class=domintro>
    <dt><var>transaction</var> .
        {{IDBTransaction/objectStore()|objectStore}}(<var>name</var>)</dt>
    <dd>
      Returns an {{IDBObjectStore}} in the [=/transaction=]'s [=transaction/scope=].
    </dd>
    <dt><var>transaction</var> . {{IDBTransaction/abort()}}</dt>
    <dd>
      Aborts the transaction. All pending [=requests=] will fail with
      a "{{AbortError}}" {{DOMException}} and all changes made to the database will be
      reverted.
    </dd>
  </dl>
</div>

The <dfn method for=IDBTransaction>objectStore(|name|)</dfn> method,
when invoked, must run these steps:

<div class=algorithm>

1. If |transaction| has [=transaction/finished=], [=throw=] an
    "{{InvalidStateError}}" {{DOMException}}.

2. Let |store| be the [=/object store=]
    [=object-store/named=] |name| in this
    [=/transaction=]'s [=transaction/scope=], or [=throw=] a
    "{{NotFoundError}}" {{DOMException}} if none.

3. Return an [=/object store handle=] associated with |store|
    and this [=/transaction=].

</div>

<aside class=note>
  Each call to this method on the same {{IDBTransaction}} instance
  with the same name returns the same {{IDBObjectStore}} instance.
</aside>

<aside class=note>
  The returned {{IDBObjectStore}} instance is specific to this
  {{IDBTransaction}}. If this method is called on a different
  {{IDBTransaction}}, a different {{IDBObjectStore}} instance is
  returned.
</aside>


The <dfn method for=IDBTransaction>abort()</dfn> method, when invoked,
must run these steps:

<div class=algorithm>

1. If this [=/transaction=] is [=transaction/finished=], [=throw=]
    an "{{InvalidStateError}}" {{DOMException}}.

2. Unset the [=/transaction=]'s [=transaction/active flag=] and run the
    [=steps for aborting a transaction=] with null as |error|.

</div>

The <dfn attribute for=IDBTransaction>onabort</dfn> attribute is the
event handler for the <code>abort</code> event.

The <dfn attribute for=IDBTransaction>oncomplete</dfn> attribute is
the event handler for the <code>complete</code> event.

The <dfn attribute for=IDBTransaction>onerror</dfn> attribute is the
event handler for the <code>error</code> event.

<aside class=note>
  To determine if a [=/transaction=] has completed successfully,
  listen to the [=/transaction=]'s <code>complete</code> event
  rather than the <code>success</code> event of a particular
  [=request=], because the [=/transaction=] may still fail after
  the <code>success</code> event fires.
</aside>

<!-- ============================================================ -->
<h3 id=domstringlist-api>The {{DOMStringList}} interface</h3>
<!-- ============================================================ -->

The {{DOMStringList}} interface represents an immutable ordered
collection of zero or more {{DOMString}} values. The items in a
{{DOMStringList}} are accessible via an integral index, starting from
zero.

<aside class=note>
  The {{DOMStringList}} interface was previously defined in
  [[DOM-Level-3-core]] but has been removed from the current versions
  of [[DOM]] and is now only referenced in this specification. It is
  hoped that in the future all uses of this type can be replaced by
  the conceptually similar <code>FrozenArray&lt;DOMString&gt;</code>
  to enable the use of other [=Array=] methods, but retaining support
  for the {{DOMStringList/contains()}} method for compatibility with
  deployed content.
</aside>

<pre class=idl>
interface DOMStringList {
    readonly attribute unsigned long length;
    getter DOMString (unsigned long index);
    DOMString? item(unsigned long index);

    boolean contains(DOMString str);
};
</pre>

<div class=note>
  <dl class=domintro>
    <dt><var>list</var> . {{DOMStringList/length}}</dt>
    <dd>
      Returns the length of the list.
    </dd>
    <dt><var>list</var> [ <var>index</var> ]</dt>
    <dt><var>list</var> . {{DOMStringList/item()|item}}(<var>index</var>)</dt>
    <dd>
      Returns the |index|th item in the list.
    </dd>
    <dt><var>list</var> . {{DOMStringList/contains()|contains}}(<var>string</var>)</dt>
    <dd>
      Returns true if the list contains |string|, or false otherwise.
    </dd>
  </dl>
</div>

The [=supported property indices=] for a {{DOMStringList}} |list|
are the numbers zero to the number of items in |list| minus one.
If |list| has no items, it has no [=supported property indices=].

To [=determine the value of an indexed property=] for a given index
|index| in a {{DOMStringList}} |list|, return the |index|<sup>th</sup>
item in |list|.

The <dfn attribute for=DOMStringList>length</dfn> attribute's
getter must return the number of items in the collection.

The <dfn method for=DOMStringList>item(|index|)</dfn> method must
return the |index|<sup>th</sup> item in the collection, or null
if there are less than |index| + 1 items in the collection.

The <dfn method for=DOMStringList>contains(|str|)</dfn> method must
return true if |str| is equal to any item in the collection, and false
otherwise.


<!-- ============================================================ -->
<h2 id=algorithms>Algorithms</h2>
<!-- ============================================================ -->

<!-- ============================================================ -->
<h3 id=opening>Opening a database</h3>
<!-- ============================================================ -->

The <dfn>steps for opening a database</dfn> are defined in the
following steps. The algorithm in these steps takes four arguments:
the |origin| which requested the [=database=] to be opened, a
database |name|, a database |version|, and a |request|.

<div class=algorithm>

1. Let |queue| be the [=connection queue=] for |origin| and |name|.

2. Add |request| to |queue|.

3. Wait until all previous requests in |queue| have been processed.

4. Let |db| be the [=database=] [=database/named=] |name| in
    |origin|, or null otherwise.

5. If |version| is undefined, let |version| be 1 if |db| is null, or
    |db|'s [=database/version=] otherwise.

6. If |db| is null, let |db| be a new [=database=] with
    [=database/name=] |name|, [=database/version=] 0 (zero), and with
    no [=/object stores=]. If this fails for any reason, return an
    appropriate error (e.g. a "{{QuotaExceededError}}" or
    "{{UnknownError}}" {{DOMException}}).

7. If |db|'s [=database/version=] is greater than |version|,
    abort these steps and return a new "{{VersionError}}" {{DOMException}}.

8. Let |connection| be a new [=/connection=] to |db|.

9. Set |connection|'s [=connection/version=] to |version|.

10. If |db|'s [=database/version=] is less than |version|, run
    these substeps:

    1. Let |openConnections| be the set of all [=/connections=],
        except |connection|, associated with |db|.

    2. For each |entry| in |openConnections| that does not have its
        [=close pending flag=] set, [=queue a task=] to [=fire a
        version change event=] named <code>versionchange</code> at
        |entry| with |db|'s [=database/version=] and |version|.

        <aside class=note>
          Firing this event might cause one or more of the other
          objects in |openConnections| to be closed, in which case the
          <code>versionchange</code> event must not be fired at those
          objects if that hasn't yet been done.
        </aside>

    3. Wait for all of the events to be fired.

    4. If any of the [=/connections=] in |openConnections| are still
        not closed, [=queue a task=] to [=fire a version change
        event=] named <code>[=request/blocked=]</code> at |request| with
        |db|'s [=database/version=] and |version|.

    5. <span id="version-change-close-block">Wait</span> until all
        [=/connections=] in |openConnections| are
        [=connection/closed=].

    6. Run the [=steps for running an upgrade transaction=]
        using |connection|, |version| and |request|.

    7. If |connection| was [=connection/closed=], create and
        return a newly <a lt="create exception">created</a>
        "{{AbortError}}" {{DOMException}} and abort these steps.

    8. If the [=upgrade transaction=] was aborted, run the [=steps
        for closing a database connection=] with |connection|,
        create and return a newly <a lt="create exception">created</a>
        "{{AbortError}}" {{DOMException}} and abort these steps.

11. Return |connection|.

</div>

<!-- ============================================================ -->
<h3 id=closing-connection>Closing a database</h3>
<!-- ============================================================ -->

The <dfn>steps for closing a database connection</dfn> are as follows.
These steps take two arguments, a |connection| object, and an
optional |forced flag|.

<div class=algorithm>

1. Set the [=close pending flag=] of |connection|.

2. If the |forced flag| is set, then for each |transaction|
    [=transaction/created=] using |connection| run the [=steps for aborting a
    transaction=] with |transaction| and newly <a lt="create
    exception">created</a> "{{AbortError}}" {{DOMException}}.

3. Wait for all transactions [=transaction/created=] using |connection| to complete.
    Once they are complete, |connection| is [=connection/closed=].

4. If the |forced flag| is set, then fire a <code>close</code> event
    at |connection|. The event must use the [=Event=] interface and
    have its type set to "<code>close</code>". The event must not
    bubble or be cancelable.

    <aside class=note>
      The "<code>close</code>" event only fires if the connection closes
      abnormally, e.g. if the user deletes browsing data, or there is
      corruption, or an I/O error. If <code>close()</code> is called explicitly
      the event <em>does not</em> fire.
    </aside>

    <aside class=advisement>
      &#x1F6A7;
      This behavior is new in this edition.
      It is supported in Chrome 31 and Firefox 50.
      &#x1F6A7;
    </aside>

</div>

<aside class=note>
  Once the [=close pending flag=] has been set no new transactions
  can be [=transaction/created=] using |connection|. All methods that
  [=transaction/create=] transactions first check the [=close pending flag=]
  first and throw an exception if it is set.
</aside>

<aside class=note>
  Once the [=/connection=] is closed, this can unblock the [=steps for
  running an upgrade transaction=], and the [=steps for deleting a
  database=], which <a href="#delete-close-block">both</a> <a
  href="#version-change-close-block">wait</a> for [=/connections=] to
  a given [=database=] to be closed before continuing.
</aside>


<!-- ============================================================ -->
<h3 id=deleting-a-database>Deleting a database</h3>
<!-- ============================================================ -->

The <dfn>steps for deleting a database</dfn> are as follows. The
algorithm in these steps takes three arguments: the |origin| that
requested the [=database=] to be deleted, a database |name|, and a
|request|.

<div class=algorithm>

1. Let |queue| be the [=connection queue=] for |origin| and |name|.

2. Add |request| to |queue|.

3. Wait until all previous requests in |queue| have been processed.

4. Let |db| be the [=database=] [=database/named=] |name| in
    |origin|, if one exists. Otherwise, return 0 (zero).

5. Let |openConnections| be the set of all [=/connections=]
    associated with |db|.

6. For each |entry| in |openConnections| that does not have its
    [=close pending flag=] set, [=queue a task=] to [=fire a version
    change event=] named <code>versionchange</code> at |entry| with
    |db|'s [=database/version=] and null.

    <aside class=note>
      Firing this event might cause one or more of the other objects
      in |openConnections| to be closed, in which case the
      <code>versionchange</code> event must not be fired at those
      objects if that hasn't yet been done.
    </aside>

7. Wait for all of the events to be fired.

8. If any of the [=/connections=] in |openConnections| are
    still not closed, [=fire a version change event=] named
    <code>[=request/blocked=]</code> at |request| with |db|'s
    [=database/version=] and null.

9. <span id="delete-close-block">Wait</span> until all
    [=/connections=] in |openConnections| are
    [=connection/closed=].

10. Let |version| be |db|'s [=database/version=].

11. Delete |db|. If this fails for any reason, return an appropriate
    error (e.g. "{{QuotaExceededError}}" or "{{UnknownError}}" {{DOMException}}).

12. Return |version|.

</div>


<!-- ============================================================ -->
<h3 id=commit-transaction>Committing a transaction</h3>
<!-- ============================================================ -->

When taking the <dfn>steps for committing a transaction</dfn> the
implementation must execute the following algorithm. This algorithm
takes one argument, the |transaction| to commit.

<div class=algorithm>

1. All the changes made to the [=database=] by |transaction| are
    written to the [=database=].

2. If an error occurs while writing the changes to the
    [=database=], abort the transaction by following the [=steps
    for aborting a transaction=] with |transaction| and an
    appropriate for the error, for example "{{QuotaExceededError}}" or
    "{{UnknownError}}" {{DOMException}}.

3. [=Queue a task=] to dispatch an event at |transaction|. The
    event must use the [=Event=] interface and have its
    {{Event/type}} set to "<code>complete</code>". The event does not
    bubble and is not cancelable.

    <aside class=note>
      Even if an exception is thrown from one of the event handlers of
      this event, the transaction is still committed since writing the
      database changes happens before the event takes places. Only
      after the transaction has been successfully written is the
      "<code>complete</code>" event fired.
    </aside>

</div>


<!-- ============================================================ -->
<h3 id=abort-transaction>Aborting a transaction</h3>
<!-- ============================================================ -->

When taking the <dfn>steps for aborting a transaction</dfn> the
implementation must execute the following algorithm. This algorithm
takes two arguments: the |transaction| to abort, and |error|.

<div class=algorithm>

1. All the changes made to the [=database=] by the [=/transaction=]
    are reverted. For [=upgrade transactions=] this includes changes
    to the set of [=/object stores=] and [=/indexes=], as well as the
    change to the [=database/version=]. Any [=/object stores=] and
    [=/indexes=] which were created during the transaction are now
    considered deleted for the purposes of other algorithms.

2. If |transaction| is an [=upgrade transaction=], run the [=steps
    for aborting an upgrade transaction=] with |transaction|. This
    reverts changes to all [=/connection=], [=/object store handle=],
    and [=index handle=] instances associated with |transaction|.

3. If |error| is not null, set |transaction|'s
    [=transaction/error=] to |error|.

4. For each |request| in |transaction|'s [=request list=] with
    [=request/done flag=] unset, abort the [=steps for asynchronously
    executing a request=] for |request| and [=queue a task=] to
    run these substeps:

    1. Set the [=request/done flag=] on |request|.
    2. Set the [=request/result=] of |request| to undefined.
    3. Set the [=request/error=] of |request| to a newly
        <a lt="create exception">created</a> "{{AbortError}}" {{DOMException}}.
    4. Dispatch an event at |request|. The event must use the
        [=Event=] interface and have its {{Event/type}} set to
        "<code>error</code>". The event bubbles and is cancelable.

    <aside class=note>
      This does not always result in any <code>error</code> events
      being fired. For example if a transaction is aborted due to an
      error while [=transaction/committing=] the transaction,
      or if it was the last remaining request that failed.
    </aside>

5. [=Queue a task=] to dispatch an event at |transaction|. The event
    must use the [=Event=] interface and have its {{Event/type}} set
    to "<code>abort</code>". The event does bubble but is not
    cancelable.

</div>


<!-- ============================================================ -->
<h3 id=async-execute-request>Asynchronously executing a [=request=]</h3>
<!-- ============================================================ -->

When taking the <dfn>steps for asynchronously executing a
request</dfn> the implementation must run the following algorithm. The
algorithm takes a |source| object and an |operation| to perform on a
database, and an optional |request|.

These steps can be aborted at any point if the [=/transaction=] the
created [=request=] belongs to is [=transaction/aborted=] using the [=steps for
aborting a transaction=].

<div class=algorithm>

1. Let |transaction| be the [=/transaction=] associated with
    |source|.

2. If |transaction| is not [=transaction/active=], [=throw=] a
    "{{TransactionInactiveError}}" {{DOMException}}.

3. If |request| was not given, let |request| be a new |request| with
    [=request/source=] as |source|.

4. Add |request| to the end of |transaction|'s [=request list=].

5. Return |request| and queue up the execution of the remaining steps
    in this algorithm.

6. Wait until all previously added [=requests=] in |transaction|
    have their [=request/done flag=] set.

7. Let |result| be the result of performing |operation|.

8. If |result| is an error, then revert all changes made by
    |operation|.

    <aside class=note>
      This only reverts the changes done by this request, not any
      other changes made by the transaction.
    </aside>

9. [=Queue a task=] to run these substeps:

    1. Set the [=request/done flag=] on |request|.

    2. If |result| is an error, then run these substeps:

        1. Set the [=request/result=] of |request| to undefined.
        2. Set the [=request/error=] of |request| to |result|.
        3. [=Fire an error event=] at |request|.

    3. Otherwise, run these substeps:

        1. Set the [=request/result=] of |request| to |result|.
        2. Set the [=request/error=] of |request| to undefined.
        3. [=Fire a success event=] at |request|.

</div>


<!-- ============================================================ -->
<h3 id=upgrade-transaction-steps>Running an upgrade transaction</h3>
<!-- ============================================================ -->

The <dfn>steps for running an upgrade transaction</dfn> are as
follows. This algorithm takes three arguments: a |connection| object
which is used to update the [=database=], a new |version| to be set
for the [=database=], and a |request|.

<div class=algorithm>

1. Let |db| be |connection|'s [=database=].

2. Let |transaction| be a new [=upgrade transaction=] with
    |connection| used as [=/connection=]. The [=transaction/scope=] of
    |transaction| includes every [=/object store=] in
    |connection|.

3. Unset |transaction|'s [=transaction/active flag=].

4. Start |transaction|.

    <aside class=note>
      Note that until this [=/transaction=] is finished, no
      other [=/connections=] can be opened to the same
      [=database=].
    </aside>

5. Let |old version| be |db|'s [=database/version=].

6. Set the version of |db| to |version|. This change is
    considered part of the [=/transaction=], and so if the
    transaction is [=transaction/aborted=], this change is reverted.

7. [=Queue a task=] to run the following steps:

    1. Set |request|'s [=request/result=] to |connection|.
    2. Set |request|'s [=request/transaction=] to |transaction|.
    3. Set the [=request/done flag=] on the [=request=].
    4. [=Fire a version change event=] named
        <code>[=upgradeneeded=]</code> at |request| with |old
        version| and |version|.
    5. If an exception was propagated out from any event handler while
        dispatching the event in the previous step, abort the
        transaction by following the [=steps for aborting a
        transaction=] with the |error| property set to a newly
        <a lt="create exception">created</a> "{{AbortError}}" {{DOMException}}.

8. Wait for |transaction| to [=transaction/finish=].

9. If |transaction| is aborted for any reason, the [=steps for
    aborting a transaction=] must be run.

10. When |transaction| is finished, immediately set |request|'s
    [=request/transaction=] to null. This must be done in the same
    task as the task firing the <code>complete</code> or
    <code>abort</code> event, but after the event has been fired.

</div>


<!-- ============================================================ -->
<h3 id=abort-upgrade-transaction>Aborting an upgrade transaction</h3>
<!-- ============================================================ -->

The <dfn>steps for aborting an upgrade transaction</dfn> |transaction|
are as follows.

<aside class=note>
  The steps are run after the normal [=steps for aborting a
  transaction=], which revert changes to the [=database=] including
  the set of associated [=/object stores=] and [=/indexes=], as well
  as the change to the [=database/version=].
</aside>

<div class=algorithm>

1. Let |connection| be |transaction|'s [=/connection=].

2. Let |database| be |connection|'s [=database=].

3. Set |connection|'s [=connection/version=] to |database|'s
    [=database/version=] if |database| previously existed, or 0 (zero)
    if |database| was newly created.

    <aside class=note>
      This reverts the value of {{IDBDatabase/version}} returned by the
      {{IDBDatabase}} object.
    </aside>

4. Set |connection|'s [=object store set=] to the set of
    [=/object stores=] in |database| if |database| previously
    existed, or the empty set if |database| was newly created.

    <aside class=note>
      This reverts the value of {{IDBDatabase/objectStoreNames}} returned
      by the {{IDBDatabase}} object.
    </aside>

5. For each [=/object store handle=] |handle| associated with
    |transaction|, including those for [=/object stores=] that
    were created or deleted during |transaction|, run these substeps:

    1. If |handle|'s [=object-store-handle/object store=] was not
        newly created during |transaction|, set |handle|'s
        [=object-store-handle/name=] to its
        [=object-store-handle/object store=]'s [=object-store/name=].

    2. Set |handle|'s [=index set=] to the set of [=/indexes=] that
        reference its [=object-store-handle/object store=].

    <aside class=note>
      This reverts the values of {{IDBObjectStore/name}} and
      {{IDBObjectStore/indexNames}} returned by related
      {{IDBObjectStore}} objects.

      Although script cannot access an [=/object store=] by using the
      {{objectStore()}} method on an {{IDBTransaction}} instance after
      the [=/transaction=] is aborted, it may still have references to
      {{IDBObjectStore}} instances where the {{IDBObjectStore/name}}
      and {{IDBObjectStore/indexNames}} properties can be queried.
    </aside>

6. For each [=index handle=] |handle| associated with |transaction|,
    including those for [=/indexes=] that were created or deleted
    during |transaction|, run these substeps:

    1. If |handle|'s [=index-handle/index=] was not newly created
        during |transaction|, set |handle|'s [=index-handle/name=] to
        its [=index-handle/index=]'s [=index/name=].

    <aside class=note>
      This reverts the value of {{IDBIndex/name}} returned by related
      {{IDBIndex}} objects.

      Although script cannot access an [=/index=] by using the
      {{index()}} method on an {{IDBObjectStore}} instance after the
      [=/transaction=] is aborted, it may still have references to
      {{IDBIndex}} instances where the {{IDBIndex/name}} property can
      be queried.
    </aside>

</div>

<aside class=note>
  The {{IDBDatabase/name}} property of the {{IDBDatabase}} instance is
  not modified, even if the aborted [=upgrade transaction=] was
  creating a new [=database=].
</aside>


<!-- ============================================================ -->
<h3 id=fire-success-event>Firing a success event</h3>
<!-- ============================================================ -->

To <dfn>fire a success event</dfn> at a [=request=],
the implementation must run the following steps:

<div class=algorithm>

1. Set |transaction| to the [=/transaction=] associated with
    the [=request/source=].

2. Set the [=transaction/active flag=] of |transaction|.

3. Dispatch an event at [=request=]. The event must use the
    [=Event=] interface and have its {{Event/type}} set to
    "<code>success</code>". The event does not bubble and is not
    cancelable.

4. Unset the [=transaction/active flag=] of |transaction|.

5. If an exception was propagated out from any event handler while
    dispatching the event in step 3, abort the transaction by
    following the [=steps for aborting a transaction=] with
    |transaction| and a newly <a lt="create exception">created</a>
    "{{AbortError}}" {{DOMException}}.

</div>


<!-- ============================================================ -->
<h3 id=fire-error-event>Firing an error event</h3>
<!-- ============================================================ -->

To <dfn>fire an error event</dfn> at a |request|,
the implementation must run the following steps:

<div class=algorithm>

1. Set |transaction| to the [=/transaction=] associated with
    the [=request/source=].

2. Set the [=transaction/active flag=] of |transaction|.

3. Dispatch an event at |request|. The event must use the [=Event=]
    interface and have its {{Event/type}} set to "<code>error</code>".
    The event bubbles and is cancelable.

4. Unset the [=transaction/active flag=] of |transaction|.

5. If an exception was propagated out from any event handler while
    dispatching the event in step 3, abort the transaction by
    following the [=steps for aborting a transaction=] with
    |transaction| and a newly <a lt="create exception">created</a>
    "{{AbortError}}" {{DOMException}} and terminate these steps. This is done even if the
    event's [=canceled flag=] is not set.

    <aside class=note>
      This means that if an error event is fired and any of the event
      handlers throw an exception, |transaction|'s
      {{IDBTransaction/error}} property is set to an {{AbortError}}
      rather than |request|'s [=request/error=], even if
      {{Event/preventDefault()}} is never called.
    </aside>

6. If the event's [=canceled flag=] is not set, run the [=steps
    for aborting a transaction=] using |transaction| and
    [=request=]'s [=request/error=].

</div>


<!-- ============================================================ -->
<h2 id=database-operations>Database operations</h2>
<!-- ============================================================ -->

This section describes various operations done on the data in
[=/object stores=] and [=/indexes=] in a [=database=].
These operations are run by the [=steps for asynchronously executing
a request=].

<!-- ============================================================ -->
<h3 id=object-store-storage-operation>Object Store Storage Operation</h3>
<!-- ============================================================ -->

The <dfn>steps for storing a record into an object store</dfn> with
|store|, |value|, an optional |key|, and a |no-overwrite flag| are as
follows.

<div class=algorithm>

1. If |store| uses [=in-line keys=], run these substeps:

    1. Let |kpk| be the result of running the steps to [=extract a
        key from a value using a key path=] with |value| and
        |store|'s [=object-store/key path=].

    2. Assert: |kpk| will not be invalid or an exception.

    3. If |kpk| is not failure, let |key| be |kpk|.

2. If |store| uses a [=key generator=], run these substeps:

    1. If |key| is undefined, run these substeps:

        1. If the [=key generator=]'s [=current number=] is
            greater than 2<sup>53</sup> (9007199254740992), then this
            operation failed with a "{{ConstraintError}}" {{DOMException}}. Abort this
            algorithm without taking any further steps.

        2. Set |key| to the [=key generator=]'s [=current number=].

        3. Increase the [=key generator=]'s [=current number=] by 1.

        4. If |store| also uses [=in-line keys=], then run the
            steps to [=inject a key into a value using a key path=]
            with |value|, |key| and |store|'s [=object-store/key
            path=].

    2. Otherwise, if the [=key/type=] of |key| is <i>number</i>
        and the [=key/value=] is greater than or equal to the
        [=key generator=]'s [=current number=], set the
        [=current number=] to lowest integer greater than |key|.

3. If the |no-overwrite flag| was given to these steps and is set, and
    a [=object-store/record=] already exists in |store| with its key [=equal to=]
    |key|, then this operation failed with a "{{ConstraintError}}" {{DOMException}}.
    Abort this algorithm without taking any further steps.

4. If a [=object-store/record=] already exists in |store| with its key [=equal
    to=] |key|, then remove the [=object-store/record=] from |store| using the
    [=steps for deleting records from an object store=].

5. Store a record in |store| containing |key| as its key and |value|
    as its value. The record is stored in the object store's
    [=object-store/list of records=] such that the list is sorted
    according key of the records in ascending order.

6. For each |index| which [=reference=] |store|, run these substeps:

    1. Let |index key| be the result of running the steps to
        [=extract a key from a value using a key path=] with
        |value|, |index|'s [=index/key path=], and |index|'s
        [=multiEntry flag=].

    2. If |index key| is an exception, or invalid, or failure, take no
        further actions for this index, and continue these substeps
        for the next index.

        <aside class=note>
          An exception thrown in this step is not rethrown.
        </aside>

    3. If |index|'s [=multiEntry flag=] is unset, or if |index key|
        is not an [=array key=], and if |index| already contains a
        [=object-store/record=] with [=/key=] [=equal to=] |index
        key|, and |index| has its [=unique flag=] set, then this
        operation failed with a "{{ConstraintError}}" {{DOMException}}. Abort this
        algorithm without taking any further steps.

    4. If |index|'s [=multiEntry flag=] is set and |index key| is
        an [=array key=], and if |index| already contains a
        [=object-store/record=] with [=/key=] [=equal to=] any of the
        [=subkeys=] of |index key|, and |index| has its [=unique
        flag=] set, then this operation failed with a
        "{{ConstraintError}}" {{DOMException}}. Abort this algorithm without taking any
        further steps.

    5. If |index|'s [=multiEntry flag=] is unset, or if |index key|
        is not an [=array key=] then store a record in |index|
        containing |index key| as its key and |key| as its value. The
        record is stored in |index|'s [=index/list of records=]
        such that the list is sorted primarily on the records keys,
        and secondarily on the records values, in ascending order.

    6. If |index|'s [=multiEntry flag=] is set and |index key| is
        an [=array key=], then for each |subkey| of the
        [=subkeys=] of |index key| store a record in |index|
        containing |subkey| as its key and |key| as its value. The
        records are stored in |index|'s [=index/list of
        records=] such that the list is sorted primarily on the
        records keys, and secondarily on the records values, in
        ascending order.

        <aside class=note>
          It is valid for there to be no [=subkeys=]. In this case
          no records are added to the index.
        </aside>

        <aside class=note>
          Even if any member of [=subkeys=] is itself an [=array key=],
          the member is used directly as the key for the index record.
          Nested [=array keys=] are not flattened or "unpacked" to
          produce multiple rows; only the outer-most [=array key=] is.
        </aside>

7. Return |key|.

</div>


<!-- ============================================================ -->
<h3 id=object-store-retrieval-operation>Object Store Retrieval Operations</h3>
<!-- ============================================================ -->

The <dfn>steps for retrieving a value from an object store</dfn> with
|store| and |range| are as follows:


<div class=algorithm>

1. Let |record| be the first [=object-store/record=] in |store|'s
    [=object-store/list of records=] whose key is [=in=] |range|, if
    any.

2. If |record| was not found, return undefined.

3. Return a [=structured clone=] of |record|'s value.

</div>


The <dfn>steps for retrieving multiple values from an object
store</dfn> with |store|, |range| and optional |count| are as follows:

<div class=algorithm>

1. If |count| is not given or is 0 (zero), let |count| be infinity.

2. Let |records| be a list containing the first |count| [=object-store/records=]
    in |store|'s [=object-store/list of records=] whose key is
    [=in=] |range|.

3. Let |list| be an empty list.

4. For each |record| in |records|, run these substeps:

    1. Let |entry| be a [=structured clone=] of |record|'s value.
    2. Append |entry| to |list|.

5. Return |list| converted to a [=sequence&lt;any&gt;=].

</div>


The <dfn>steps for retrieving a key from an object store</dfn> with
|store| and |range| are as follows:

<div class=algorithm>

1. Let |record| be the first [=object-store/record=] in |store|'s
    [=object-store/list of records=] whose key is [=in=] |range|, if
    any.

2. If |record| was not found, return undefined.

3. Return the result of running the steps to [=convert a
    key to a value=] with |record|'s key.

</div>


The <dfn>steps for retrieving multiple keys from an object store</dfn>
with |store|, |range| and optional |count| are as follows:

<div class=algorithm>

1. If |count| is not given or is 0 (zero), let |count| be infinity.

2. Let |records| be a list containing the first |count| [=object-store/records=]
    in |store|'s [=object-store/list of records=] whose key is
    [=in=] |range|.

3. Let |list| be an empty list.

4. For each |record| in |records|, run these substeps:

    1. Let |entry| be the result of running the steps to [=convert a
        key to a value=] with |record|'s key.
    2. Append |entry| to |list|.

5. Return |list| converted to a [=sequence&lt;any&gt;=].

</div>


<!-- ============================================================ -->
<h3 id=index-retrieval-operation>Index Retrieval Operations</h3>
<!-- ============================================================ -->

The <dfn>steps for retrieving a referenced value from an index</dfn>
with |index| and |range| are as follows.

<div class=algorithm>

1. Let |record| be the first [=object-store/record=] in |index|'s [=index/list of
    records=] whose key is [=in=] |range|, if any.

2. If |record| was not found, return undefined.

3. Return a [=structured clone=] of |record|'s [=referenced
    value=].

</div>


The <dfn>steps for retrieving multiple referenced values from an
index</dfn> with |index|, |range| and optional |count| are as follows:

<div class=algorithm>
1. If |count| is not given or is 0 (zero), let |count| be infinity.

2. Let |records| be a list containing the first |count| [=object-store/records=]
    in |index|'s [=index/list of records=] whose key is [=in=] |range|.

3. Let |list| be an empty list.

4. For each |record| in |records|, run these substeps:

    1. Let |entry| be a [=structured clone=] of |record|'s
        [=referenced value=].
    2. Append |entry| to |list|.

5. Return |list| converted to a [=sequence&lt;any&gt;=].

</div>

<aside class=note>
    The [=index/values=] of an [=index/record=] in an index are the keys of
    [=object-store/records=] in the [=index/referenced=] object store.
</aside>

The <dfn>steps for retrieving a value from an index</dfn> with
|index| and |range| are as follows.

<div class=algorithm>

1. Let |record| be the first [=index/record=] in |index|'s [=index/list of
    records=] whose key is [=in=] |range|, if any.

2. If |record| was not found, return undefined.

3. Return the of running the steps to [=convert a
        key to a value=] with |record|'s [=/value=].

</div>


The <dfn>steps for retrieving multiple values from an index</dfn> with
|index|, |range| and optional |count| are as follows:


<div class=algorithm>

1. If |count| is not given or is 0 (zero), let |count| be infinity.

2. Let |records| be a list containing the first |count| [=index/records=] in
    |index|'s [=index/list of records=] whose key is [=in=] |range|.

3. Let |list| be an empty list.

4. For each |record| in |records|, run these substeps:

    1. Let |entry| be the result of running the steps to [=convert a
        key to a value=] with |record|'s value.
    2. Append |entry| to |list|.

5. Return |list| converted to a [=sequence&lt;any&gt;=].

</div>


<!-- ============================================================ -->
<h3 id=object-store-deletion-operation>Object Store Deletion Operation</h3>
<!-- ============================================================ -->

The <dfn>steps for deleting records from an object store</dfn>
with |store| and |range| are as follows.

<div class=algorithm>

1. Remove all records, if any, from |store|'s [=object-store/list
    of records=] with key [=in=]
    |range|.

2. For each |index| which [=references=] |store|, remove every
    [=object-store/record=] from |index|'s [=index/list of records=] whose value is
    [=in=] |range|, if any such records exist.

3. Return undefined.

</div>


<!-- ============================================================ -->
<h3 id=record-counting-operation>Record Counting Operation</h3>
<!-- ============================================================ -->

The <dfn>steps to count the records in a range</dfn> with |source| and
|range| are as follows:

<div class=algorithm>

1. Let |count| be the number of records, if any, in |source|'s list of
    records with key [=in=] |range|.

2. Return |count|.

</div>


<!-- ============================================================ -->
<h3 id=object-store-clear-operation>Object Store Clear Operation</h3>
<!-- ============================================================ -->

The <dfn>steps for clearing an object store</dfn> with |store| are as follows.

<div class=algorithm>

1. Remove all records from |store|.

2. In all [=/indexes=] which [=reference=] |store|, remove all
    [=object-store/records=].

3. Return undefined.

</div>


<!-- ============================================================ -->
<h3 id=cursor-iteration-operation>Cursor Iteration Operation</h3>
<!-- ============================================================ -->

The <dfn>steps for iterating a cursor</dfn> with |cursor|, an optional
|key| and |primaryKey| to iterate to, and an optional |count| are as
follows.

<div class=algorithm>

1. Let |source| be |cursor|'s [=cursor/source=].

2. Let |direction| be |cursor|'s [=cursor/direction=].

3. Assert: if |primaryKey| is given, |source| is an [=/index=]
    and |direction| is {{"next"}} or {{"prev"}}.

4. Let |records| be the list of [=object-store/records=] in |source|.

    <aside class=note>
      |records| is always sorted in ascending [=/key=] order.
      In the case of |source| being an [=/index=], |records|
      is secondarily sorted in ascending [=/value=] order
      (where the value in an [=/index=] is the
      [=/key=] of the [=object-store/record=] in the referenced
      [=/object store=]).
    </aside>

5. Let |range| be |cursor|'s [=cursor/range=].

6. Let |position| be |cursor|'s [=cursor/position=].

7. Let |object store position| be |cursor|'s [=object store position=].

8. If |count| is not given, let |count| be 1.

9. While |count| is greater than 0, run these substeps:

    1. Switch on |direction|:

        <dl class=switch>
          <dt>{{"next"}}</dt>
          <dd>
            Let |found record| be the first record in |records| which
            satisfy all of the following requirements:

            * If |key| is defined, the record's key is [=greater
                than=] or [=equal to=] |key|.

            * If |primaryKey| is defined, the record's key is [=equal
                to=] |key| and the record's value is [=greater
                than=] or [=equal to=] |primaryKey|, or the
                record's key is [=greater than=] |key|.

            * If |position| is defined, and |source| is an
                [=/object store=], the record's key is [=greater than=]
                |position|.

            * If |position| is defined, and |source| is an
                [=/index=], the record's key is [=equal to=]
                |position| and the record's value is [=greater
                than=] |object store position| or the record's key is
                [=greater than=] |position|.

            * The record's key is [=in=]
                |range|.

          </dd>

          <dt>{{"nextunique"}}</dt>
          <dd>
            Let |found record| be the first record in |records| which
            satisfy all of the following requirements:

            * If |key| is defined, the record's key is [=greater
                than=] or [=equal to=] |key|.

            * If |position| is defined, the record's key is [=greater
                than=] |position|.

            * The record's key is [=in=]
                |range|.

          </dd>

          <dt>{{"prev"}}</dt>
          <dd>
            Let |found record| be the last record in |records| which
            satisfy all of the following requirements:

            * If |key| is defined, the record's key is [=less
                than=] or [=equal to=] |key|.

            * If |primaryKey| is defined, the record's key is [=equal
                to=] |key| and the record's value is [=less than=]
                or [=equal to=] |primaryKey|, or the record's key is
                [=less than=] |key|.

            * If |position| is defined, and |source| is an
                [=/object store=], the record's key is [=less
                than=] |position|.

            * If |position| is defined, and |source| is an
                [=/index=], the record's key is [=equal to=]
                |position| and the record's value is [=less than=]
                |object store position| or the record's key is
                [=less than=] |position|.

            * The record's key is [=in=] |range|.

          </dd>

          <dt>{{"prevunique"}}</dt>
          <dd>
            Let |temp record| be the last record in
            |records| which satisfy all of the following requirements:

            * If |key| is defined, the record's key is [=less
                than=] or [=equal to=] |key|.

            * If |position| is defined, the record's key is [=less
                than=] |position|.

            * The record's key is [=in=]
                |range|.

            If |temp record| is defined, let |found record| be the
            first record in |records| whose key is [=equal to=]
            |temp record|'s key.

            <aside class=note>
              Iterating with {{"prevunique"}} visits the same records that
              {{"nextunique"}} visits, but in reverse order.
            </aside>

          </dd>
        </dl>

    2. If |found record| is not defined, run these substeps:

        1. Set |cursor|'s [=cursor/key=] to undefined.

        2. If |source| is an [=/index=], set |cursor|'s
            [=object store position=] to undefined.

        3. If |cursor|'s [=key only flag=] is unset, set |cursor|'s
            [=cursor/value=] to undefined.

        4. Return null.

    3. Let |position| be |found record|'s key.

    4. If |source| is an [=/index=], let |object store
        position| be |found record|'s value.

    5. Decrease |count| by 1.

10. Set |cursor|'s [=cursor/position=] to |position|.

11. If |source| is an [=/index=], set |cursor|'s [=object
    store position=] to |object store position|.

12. Set |cursor|'s [=cursor/key=] to |found record|'s key.

13. If |cursor|'s [=key only flag=] is unset, set |cursor|'s
    [=cursor/value=] to a [=structured clone=] of |found
    record|'s [=referenced value=].

14. Set |cursor|'s [=got value flag=].

15. Return |cursor|.

</div>


<!-- ============================================================ -->
<h2 id=binding>ECMAScript binding</h2>
<!-- ============================================================ -->

This section defines how [=/key=] values defined in this specification
are converted to and from ECMAScript values, and how they may be
extracted from and injected into ECMAScript values using [=/key
paths=]. This section references types and algorithms and uses some
algorithm conventions from the ECMAScript Language Specification.
[[!ECMA-262]]

<aside class=issue>
  Simplify this section as much as possible by relying more on [[!WEBIDL]]
  for key conversion logic.
</aside>

<!-- ============================================================ -->
<h3 id=extract-key-from-value>Extract a key from a value</h3>
<!-- ============================================================ -->


The steps to <dfn>extract a key from a value using a key path</dfn>
with |value|, |keyPath| and an optional |multiEntry flag| are as
follows. The result of these steps is a [=/key=], invalid, or
failure, or the steps may throw an exception.

<div class=algorithm>

1. Let |r| be the result of running the steps to [=evaluate a key
    path on a value=] with |value| and |keyPath|. Rethrow any
    exceptions.

2. If |r| is failure, return failure.

3. Let |key| be the result of running the steps to [=convert a value
    to a key=] with |r| if the |multiEntry flag| is unset, and the
    result of running the steps to [=convert a value to a multiEntry
    key=] with |r| otherwise. Rethrow any exceptions.

4. If |key| is invalid, return invalid.

5. Return |key|.

</div>


The steps to <dfn>evaluate a key path on a value</dfn> with |value|
and |keyPath| are as follows. The result of these steps is an
ECMAScript value or failure, or the steps may throw an exception.

<div class=algorithm>

1. If |keyPath| is a [=sequence&lt;DOMString&gt;=], run these substeps:

    1. Let |result| be a new [=Array=] object created as if by the
        expression <code>[]</code>.

    2. Let |i| be 0.

    3. For each |item| in the |keyPath| sequence, run these substeps:

        1. Let |key| be the result of recursively running the steps to
            [=extract a key from a value using a key path=] using
            |item| as |keyPath| and |value| as |value|.

        2. Assert: |key| is not an [=abrupt completion=].

        3. If |key| is failure, abort the overall algorithm and return
            failure.

        4. Let |p| be ! [=ToString=](|i|).

        5. Let |status| be [=CreateDataProperty=](|result|, |p|, |key|).

        6. Assert: |status| is true.

        7. Increase |i| by 1.

    4. Return |result|.

        <aside class=note>
          This will only ever "recurse" one level since [=/key
          path=] sequences can't ever be nested.
        </aside>

2. If |keyPath| is the empty string, return |value| and skip the
    remaining steps.

3. Let |identifiers| be the result of [=strictly splitting the
    string=] |keyPath| on U+002E FULL STOP characters (.).

4. For each |identifier| in |identifiers|, jump to the appropriate step below:

    <dl class=switch>
      <dt>If [=/Type=](|value|) is String, and |identifier| is "<code>length</code>"</dt>
      <dd>Let |value| be a Number equal to the number of elements in |value|.</dd>

      <dt>If |value| is an [=Array=] and |identifier| is "<code>length</code>"</dt>

      <dd>Let |value| be [=!=] [=ToLength=]([=!=] [=Get=](|value|, "<code>length</code>")).</dd>

      <dt>If |value| is a {{Blob}} and |identifier| is "<code>size</code>"</dt>
      <dd>Let |value| be a Number equal to |value|'s {{Blob/size}}.</dd>

      <dt>If |value| is a {{Blob}} and |identifier| is "<code>type</code>"</dt>
      <dd>Let |value| be a String equal to |value|'s {{Blob/type}}.</dd>

      <dt>If |value| is a {{File}} and |identifier| is "<code>name</code>"</dt>
      <dd>Let |value| be a String equal to |value|'s {{File/name}}.</dd>

      <dt>If |value| is a {{File}} and |identifier| is "<code>lastModified</code>"</dt>
      <dd>Let |value| be a Number equal to |value|'s {{File/lastModified}}.</dd>

      <dt>If |value| is a {{File}} and |identifier| is "<code>lastModifiedDate</code>"</dt>
      <dd>Let |value| be a new [=Date=] object with \[[DateValue]] internal slot
        equal to |value|'s {{File/lastModified}}.</dd>

      <dt>Otherwise</dt>
      <dd>
        1. If [=/Type=](|value|) is not Object, return failure.

        2. Let |hop| be [=!=] [=HasOwnProperty=](|value|, |identifier|).

        3. If |hop| is false, return failure.

        4. Let |value| be [=!=] [=Get=](|value|, |identifier|).

        5. If |value| is undefined, return failure.
      </dd>

    </dl>

5. Assert: |value| is not an [=abrupt completion=].

6. Return |value|.

</div>

<aside class=note>
  Assertions can be made in the above steps because this algorithm is
  only applied to values that are the output of the [=structured clone
  algorithm=] and only access "own" properties.
</aside>


<!-- ============================================================ -->
<h3 id=inject-key-into-value>Inject a key into a value</h3>
<!-- ============================================================ -->

The steps to <dfn>inject a key into a value using a key path</dfn> are
as follows. The algorithm takes a |value|, a |key| and a |keyPath|.

<div class=algorithm>

1. Let |identifiers| be the result of [=strictly splitting the
    string=] |keyPath| on U+002E FULL STOP characters (.).

2. Assert: |identifiers| is not empty.

3. Let |last| be the last member of |identifiers| and remove it from
    the list.

4. For each remaining |identifier| in |identifiers|, run these
    substeps:

    1. If |value| is not an [=Object=] object or an [=Array=]
        object (see [=structured clone algorithm=] [[!HTML]]), then
        [=throw=] a "{{DataError}}" {{DOMException}}.

    2. Let |hop| be [=!=] [=HasOwnProperty=](|value|, |identifier|).

    3. If |hop| is false, run these substeps:

         1. Let |o| be a new [=Object=] created as if by the
            expression <code>({})</code>.

         2. Let |status| be [=CreateDataProperty=](|value|, |identifier|,
            |o|).

         3. Assert: |status| is true.

    4. Let |value| be [=!=] [=Get=](|value|, |identifier|).

5. Assert: |value| is an [=Object=] or an [=Array=].

6. Let |keyValue| be the result of running the steps to [=convert a
    key to a value=].

7. Let |status| be [=CreateDataProperty=](|value|, |last|, |keyValue|).

8. Assert: |status| is true.

</div>

<aside class=note>
  The [=/key path=] used here is always a string and never a sequence,
  since it is not possible to create a [=/object store=] which has a
  [=key generator=] and also has a [=object-store/key path=] that is a
  sequence.
</aside>

<aside class=note>
  Assertions can be made in the above steps because this algorithm is
  only applied to values that are the output of the [=structured clone
  algorithm=].
</aside>


<!-- ============================================================ -->
<h3 id=convert-key-to-value>Convert a key to a value</h3>
<!-- ============================================================ -->

The steps to <dfn>convert a key to a value</dfn> are as follows. These
steps take one argument, |key|, and return an ECMAScript value.

<div class=algorithm>

1. Let |type| be |key|'s [=key/type=].

2. Let |value| be |key|'s [=key/value=].

3. Switch on |type|:

    <dl class=switch>
      <dt><i>number</i></dt>
      <dd>Return an ECMAScript Number value equal to |value|</dd>

      <dt><i>string</i></dt>
      <dd>Return an ECMAScript String value equal to |value|</dd>

      <dt><i>date</i></dt>
      <dd>
        1. Let |date| be the result of executing the ECMAScript Date
            constructor with the single argument |value|.
        2. Assert: |date| is not an [=abrupt completion=].
        3. Return |date|.

      </dd>

      <dt><i>binary</i></dt>
      <dd>
        1. Let |len| be the length of |value|.
        2. Let |buffer| be the result of executing the ECMAScript
            ArrayBuffer constructor with |len|.
        3. Assert: |buffer| is not an [=abrupt completion=].
        4. Set the entries in |buffer|'s
            \[[ArrayBufferData]] internal slot to the entries
            in |value|.
        5. Return |buffer|.

      </dd>

      <dt><i>array</i></dt>
      <dd>
        1. Let |array| be the result of executing the ECMAScript Array
            constructor with no arguments.
        2. Assert: |array| is not an [=abrupt completion=].
        3. Let |len| be the length of |value|.
        4. Let |index| be 0.
        5. While |index| is less than |len|, run these substeps:

            1. Let |entry| be the result of running the steps to
                [=convert a key to a value=] with the |index|th
                entry of |value| as input.
            2. Let |status| be [=CreateDataProperty=](|array|, |index|,
                |entry|).
            3. Assert: |status| is true.
            4. Increase |index| by 1.

        6. Return |array|.

      </dd>
    </dl>

</div>


<!-- ============================================================ -->
<h3 id=convert-value-to-key>Convert a value to a key</h3>
<!-- ============================================================ -->

The steps to <dfn>convert a value to a key</dfn> are as follows. These
steps take two arguments, an ECMAScript value |input|, and an optional
set |seen|. The result of these steps is a [=/key=] or invalid, or the
steps may throw an exception.

<div class=algorithm>

1. If |seen| was not given, let |seen| be a new empty set.

2. If |input| is in |seen| return invalid.

3. Jump to the appropriate step below:

    <dl class=switch>

      <!-- Number -->
      <dt>If [=/Type=](|input|) is Number</dt>
      <dd>
        1. If |input| is NaN then return invalid.
        2. Otherwise, return a new [=/key=] with
            [=key/type=] <i>number</i> and [=key/value=]
            |input|.

      </dd>

      <!-- Date -->
      <dt>If |input| is a [=Date=] (has a \[[DateValue]] internal slot)</dt>
      <dd>
        1. Let |ms| be the value of |input|'s
            \[[DateValue]] internal slot.

        2. If |ms| is NaN then return invalid.

        3. Otherwise, return a new [=/key=] with [=key/type=]
            <i>date</i> and [=key/value=] |ms|.

      </dd>

      <!-- String -->
      <dt>If [=/Type=](|input|) is String</dt>
      <dd>

        1. Return a new [=/key=] with [=key/type=] <i>string</i> and
            [=key/value=] |input|.

      </dd>

      <!-- Binary -->
      <dt>
        If |input| is a [=buffer source type=]</dt>
      <dd>

        1. Let |octets| be the result of running the steps for
            [=getting a copy of the bytes held by a buffer source=]
            with |value|. Rethrow any exceptions.

        2. Return a new [=/key=] with [=key/type=]
            <i>binary</i> and [=key/value=] |octets|.

      </dd>

      <!-- Array -->
      <dt>If [=IsArray=](|input|)</dt>
      <dd>

        1. Let |len| be [=?=] [=ToLength=]( [=?-] [=Get=](|input|,
            "<code>length</code>")).
        2. Add |input| to |seen|.
        3. Let |keys| be a new empty list.
        4. Let |index| be 0.
        5. While |index| is less than |len|, run these substeps:

            1. Let |hop| be [=?=] [=HasOwnProperty=](|input|, |index|).

            2. If |hop| is false, return invalid.

            3. Let |entry| be [=?=] [=Get=](|input|, |index|).

            4. Let |key| be the result of running the steps to
                [=convert a value to a key=] with arguments |entry|
                and |seen|.

            5. [=ReturnIfAbrupt=](|key|).

            6. If |key| is invalid abort these steps and return
                invalid.

            7. Append |key| to |keys|.

            8. Increase |index| by 1.

        6. Return a new [=array key=] with [=key/value=]
            |keys|.

      </dd>

      <dt>Otherwise</dt>
      <dd>Return invalid.</dd>
    </dl>

</div>


The steps to <dfn>convert a value to a multiEntry key</dfn> are as
follows. These steps take one argument, an ECMAScript value |input|.
The result of these steps is a [=/key=] or invalid, or the
steps may throw an exception.

<div class=algorithm>

1. If [=IsArray=](|input|), then:

    1. Let |len| be [=?=] ToLength( [=?=] [=Get=](|input|, "<code>length</code>")).

    2. Let |seen| be a new set containing only |input|.

    3. Let |keys| be a new empty set.

    4. Let |index| be 0.

    5. While |index| is less than |len|, run these substeps:

        1. Let |entry| be [=Get=](|input|, |index|).

        2. If |entry| is not an [=abrupt completion=], run these substeps:

             1. Let |key| be the result of running the steps to
                 [=convert a value to a key=] with arguments
                 |entry| and |seen|.

             2. If |key| is not invalid or an [=abrupt completion=],
                 add |key| to |keys| if there are no other members of
                 |keys| [=equal to=] |key|.

        3. Increase |index| by 1.

   6. Return a new [=array key=] with [=key/value=] set to
       a list of the members of |keys|.

2. Otherwise, return the result of running the steps to [=convert a
    value to a key=] with argument |input|.

</div>

<aside class=note>
  These steps are similar to those to [=convert a value to a key=]
  but if the top-level value is an [=Array=] then members which can
  not be converted to keys are ignored, and duplicates are removed.

  For example, the value <code>[10, 20, null, 30, 20]</code> is
  converted to an [=array key=] with [=subkeys=] 10, 20, 30.
</aside>


<!-- ============================================================ -->
<h2 id=privacy>Privacy Considerations</h2>
<!-- ============================================================ -->

<em>This section is non-normative.</em>

<h3 id=user-tracking>User tracking</h3>

A third-party host (or any object capable of getting content
distributed to multiple sites) could use a unique identifier stored in
its client-side database to track a user across multiple sessions,
building a profile of the user's activities. In conjunction with a
site that is aware of the user's real id object (for example an
e-commerce site that requires authenticated credentials), this could
allow oppressive groups to target individuals with greater accuracy
than in a world with purely anonymous Web usage.

There are a number of techniques that can be used to mitigate the risk
of user tracking:


<dl>
<dt>Blocking third-party storage</dt>
<dd>
User agents may restrict access to the database objects
to scripts originating at the domain of the top-level document of
the <span>browsing context</span>, for instance denying access to
the API for pages from other domains running in <code>iframe</code>s.
</dd>

<dt>Expiring stored data</dt>
<dd>

User agents may automatically delete stored data after a period of
time.

This can restrict the ability of a site to track a user, as the site
would then only be able to track the user across multiple sessions
when she authenticates with the site itself (e.g. by making a purchase
or logging in to a service).

However, this also puts the user's data at risk.
</dd>

<dt>Treating persistent storage as cookies</dt>
<dd>

User agents should present the database feature to the user in a way
that associates them strongly with HTTP session cookies. [[COOKIES]]

This might encourage users to view such storage with healthy
suspicion.

</dd>

<dt>Site-specific safe-listing of access to databases</dt>
<dd>

User agents may require the user to authorize access to databases
before a site can use the feature.

</dd>

<dt>Origin-tracking of stored data</dt>
<dd>

User agents may record the [=origins=] of sites that contained content
from third-party origins that caused data to be stored.

If this information is then used to present the view of data
currently in persistent storage, it would allow the user to make
informed decisions about which parts of the persistent storage to
prune. Combined with a blocklist ("delete this data and prevent
this domain from ever storing data again"), the user can restrict
the use of persistent storage to sites that she trusts.

</dd>

<dt>Shared blocklists</dt>
<dd>

User agents may allow users to share their persistent storage
domain blocklists.

This would allow communities to act together to protect their
privacy.

</dd>
</dl>

While these suggestions prevent trivial use of this API for user
tracking, they do not block it altogether. Within a single domain, a
site can continue to track the user during a session, and can then
pass all this information to the third party along with any
identifying information (names, credit card numbers, addresses)
obtained by the site. If a third party cooperates with multiple
sites to obtain such information, a profile can still be
created.

However, user tracking is to some extent possible even with no
cooperation from the user agent whatsoever, for instance by using
session identifiers in URLs, a technique already commonly used for
innocuous purposes but easily repurposed for user tracking (even
retroactively). This information can then be shared with other
sites, using using visitors' IP addresses and other user-specific
data (e.g. user-agent headers and configuration settings) to combine
separate sessions into coherent user profiles.


<h3 id=cookie-resurrection>Cookie resurrection</h3>

If the user interface for persistent storage presents data in the
persistent storage features described in this specification separately
from data in HTTP session cookies, then users are likely to delete
data in one and not the other. This would allow sites to use the two
features as redundant backup for each other, defeating a user's
attempts to protect his privacy.


<h3 id=sensitivity-of-data>Sensitivity of data</h3>

User agents should treat persistently stored data as potentially
sensitive; it is quite possible for e-mails, calendar appointments,
health records, or other confidential documents to be stored in this
mechanism.

To this end, user agents should ensure that when deleting data,
it is promptly deleted from the underlying storage.


<!-- ============================================================ -->
<h2 id=security>Security Considerations</h2>
<!-- ============================================================ -->

<h3 id=dns-spoofing-attacks>DNS spoofing attacks</h3>

Because of the potential for DNS spoofing attacks, one cannot
guarantee that a host claiming to be in a certain domain really is
from that domain. To mitigate this, pages can use TLS. Pages using TLS
can be sure that only pages using TLS that have certificates
identifying them as being from the same domain can access their
databases.


<h3 id=cross-directory-attacks>Cross-directory attacks</h3>

Different authors sharing one host name, for example users hosting
content on <code>geocities.com</code>, all share one set of databases.

There is no feature to restrict the access by pathname. Authors on
shared hosts are therefore recommended to avoid using these features,
as it would be trivial for other authors to read the data and
overwrite it.

<aside class=note>
  Even if a path-restriction feature was made available, the usual DOM
  scripting security model would make it trivial to bypass this
  protection and access the data from any path.
</aside>

<h3 id=implementation-risks>Implementation risks</h3>

The two primary risks when implementing these persistent storage
features are letting hostile sites read information from other
domains, and letting hostile sites write information that is then read
from other domains.

Letting third-party sites read data that is not supposed to be read
from their domain causes <em>information leakage</em>, For example, a
user's shopping wish list on one domain could be used by another
domain for targeted advertising; or a user's work-in-progress
confidential documents stored by a word-processing site could be
examined by the site of a competing company.

Letting third-party sites write data to the persistent storage of
other domains can result in <em>information spoofing</em>, which is
equally dangerous. For example, a hostile site could add records to a
user's wish list; or a hostile site could set a user's session
identifier to a known ID that the hostile site can then use to track
the user's actions on the victim site.

Thus, strictly following the <span>origin</span> model described in
this specification is important for user security.


<!-- ============================================================ -->
<h2 id=revision-history>Revision History</h2>
<!-- ============================================================ -->

The following is an informative summary of the changes since the last
publication of this specification. A complete revision history can be
found <a href="https://github.com/w3c/IndexedDB/">here</a>. For the
revision history of the first edition, see <a
href="https://www.w3.org/TR/IndexedDB/#revision-history">that
document's Revision History</a>.


* Address comparison of empty arrays.
    (<a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=27712">bug #27712</a>)

* Added {{IDBObjectStore/openKeyCursor()}} on {{IDBObjectStore}}.
    (<a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=19955">bug #19955</a>)

* Correct |source| used for
    {{IDBIndex/get()}},
    {{IDBIndex/getKey()}} and
    {{IDBIndex/openKeyCursor()}} on {{IDBIndex}}.

* Added details around garbage collection of {{IDBDatabase}} objects.
    (<a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=25223">bug #25223</a>)

* Added <code>[Exposed=(Window,Worker)]</code> annotations to interfaces.

* Added |forced flag| to the [=steps for closing a database connection=],
    described the firing of a "<code>close</code>" event, and
    {{IDBDatabase/onclose}}.
    (<a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=22540">bug #22540</a>)

* Converted specification to a more algorithmic style,
    and define abstract types such as [=/key=] more rigorously.
    (<a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=17681">bug #17681</a>)

* Added
    {{IDBObjectStore/getAll()}} and
    {{IDBObjectStore/getAllKeys()}} on {{IDBObjectStore}}, and
    {{IDBIndex/getAll()}} and
    {{IDBIndex/getAllKeys()}} on {{IDBIndex}}.
    (<a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16595">bug #16595</a>)

* Replaced {{DOMError}} with {{DOMException}}.
    (<a href="https://github.com/w3c/IndexedDB/issues/16">bug #16</a>)

* Added {{IDBTransaction/objectStoreNames}} on {{IDBTransaction}}.
    (<a href="https://github.com/w3c/IndexedDB/issues/18">bug #18</a>)

* Added <i>binary</i> [=/keys=], including comparisons and ECMAScript bindings.
    (<a href="https://github.com/w3c/IndexedDB/issues/21">bug #21</a>)

* Allow renaming stores and indexes via {{IDBObjectStore}}'s {{IDBObjectStore/name}}
    and {{IDBIndex}}'s {{IDBIndex/name}} attribute setters.
    (<a href="https://github.com/w3c/IndexedDB/issues/21">bug #22</a>)

* Added {{IDBCursor/continuePrimaryKey()}} on {{IDBCursor}}.
    (<a href="https://github.com/w3c/IndexedDB/issues/14">bug #14</a>)

* Added {{IDBKeyRange/includes()}} on {{IDBKeyRange}}.
    (<a href="https://github.com/w3c/IndexedDB/issues/41">bug #41</a>)

* Added {{IDBObjectStore/getKey()}} on {{IDBObjectStore}}.
    (<a href="https://github.com/w3c/IndexedDB/issues/26">bug #26</a>)

* Clarified when a transaction can attempt to commit.
    (<a href="https://github.com/w3c/IndexedDB/issues/77">bug #77</a>)

* Clarified [=open request=] / [=connection queue=] processing.
    (<a href="https://github.com/w3c/IndexedDB/issues/9">bug #9</a>,
    <a href="https://github.com/w3c/IndexedDB/issues/77">bug #78</a>,
    <a href="https://github.com/w3c/IndexedDB/issues/77">bug #79</a>,
    <a href="https://github.com/w3c/IndexedDB/issues/77">bug #81</a>)

* Added {{DOMStringList}}.
    (<a href="https://github.com/w3c/IndexedDB/issues/28">bug #28</a>)


<!-- ============================================================ -->
<h2 id=acknowledgements>Acknowledgements</h2>
<!-- ============================================================ -->

Special thanks to Nikunj Mehta, the original author of the first
edition, and Jonas Sicking, Eliot Graff, Andrei Popescu, and Jeremy
Orlow, additional editors of the first edition.

Garret Swart was extremely influential in the design of this specification.

Thanks to Tab Atkins, Jr. for creating and maintaining <a
href="https://github.com/tabatkins/bikeshed">Bikeshed</a>, the
specification authoring tool used to create this document.

Special thanks to
Chris Anderson,
Pablo Castro,
Victor Costan,
Kristof Degrave,
Jake Drew,
Ben Dilts,
Jo&atilde;o Eiras,
Alec Flett,
Dana Florescu,
David Grogan,
Israel Hilerio,
Kyle Huey,
Philip Jägenstedt,
Laxminarayan G Kamath A,
Anne van Kesteren,
Adam Klein,
Tobie Langel,
Kang-Hao Lu,
Andrea Marchesini,
Glenn Maynard,
Ms2ger,
Odin Omdal,
Danillo Paiva,
Olli Pettay,
Simon Pieters,
Anthony Ramine,
Yonathan Randolph,
Arun Ranganathan,
Margo Seltzer,
Maciej Stachowiak,
Bevis Tseng,
Ben Turner,
Kyaw Tun,
Hans Wennborg,
Shawn Wilsher,
Brett Zamir,
Boris Zbarsky,
Zhiqiang Zhang,
and
Kris Zyp,
all of whose feedback and suggestions have led to improvements to this
specification.