Indexed Database API 2.0

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 of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This is the Second Edition of Indexed Database API. The First Edition became a W3C Recommendation on 8 January 2015.

The concepts referenced from [CSS-CASCADE-4] and [DOM41] have been stable for a long time and are not expected to change while those specifications progress toward W3C Recommendation.

This document was published by the Web Platform Working Group as a W3C Recommendation.

The W3C Membership and other interested parties are invited to review the document and send comments to [email protected] (subscribe, archives) or file a bug on GitHub.

Please see the Working Group's implementation report.

This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

1. Introduction

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.

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.

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;
};

The following example populates the database using a transaction.

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.
};

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

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);
  }
};

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

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);
  }
};

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

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(event) {
  // The uniqueness constraint of the "by_title" index failed.
  report(request.error);
  // Could call event.preventDefault() to prevent the transaction from aborting.
};
tx.onabort = function() {
  // Otherwise the transaction will automatically abort due the failed request.
  report(tx.error);
};

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

db.close();

In the future, the database might 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.

var request = indexedDB.open("library", 3); // Request version 3.

request.onupgradeneeded = function(event) {
  var db = request.result;
  if (event.oldVersion < 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 < 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 < 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.
};

A single database can be used by multiple clients (pages and workers) simultaneously — transactions ensure they don’t clash while reading and writing. 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 can listen for the version change 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:

db.onversionchange = function() {
  // First, save any unsaved data:
  saveUnsavedData().then(function() {
    // If the document isn’t being actively used, it could 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 can 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.
}

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

db.onversionchange = function() {
  saveUnsavedData().then(function() {
    db.close();
    stopUsingTheDatabase();
  });
};

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

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.

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.
}

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

2. Constructs

A name is a string equivalent to a DOMString; that is, an arbitrary sequence of 16-bit code units of any length, including the empty string. Names are always compared as opaque sequences of 16-bit code units.

As a result, name comparison is sensitive to variations in case as well as other minor variations such as normalization form, the inclusion or omission of controls, and other variations in Unicode text. [Charmod-Norm]

If an implementation uses a storage mechanism which does not support arbitrary strings, the implementation can use an escaping mechanism or something similar to map the provided name to a string that it can store.

A sorted name list is a list containing names sorted in ascending order by 16-bit code unit.

Details

2.1. Database

Each origin has an associated set of databases. A database has zero or more object stores which hold the data stored in the database.

A database has a name which identifies it within a specific origin. The name is a name, and stays constant for the lifetime of the database.

A database has a version. When a database is first created, its version is 0 (zero).

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.

A database has at most one associated upgrade transaction, which is either null or an upgrade transaction, and is initially null.

2.1.1. Database Connection

Script does not interact with databases directly. Instead, script has indirect access via a connection. 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.

A connection can only access databases associated with the origin of the global scope from which the connection is opened.

This is not affected by changes to the Document's domain.

A connection has a version, which is set when the connection is created. It remains constant for the lifetime of the connection unless an upgrade is aborted, in which case it is set to the previous version of the database. Once the connection is closed the version does not change.

Each connection has a close pending flag which is initially unset.

When a connection is initially created it is in opened state. The connection can be closed 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 to close 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 to close a database connection with the connection and with the forced flag set.

🚧 This behavior is new in this edition. It is supported in Chrome 31, Firefox 50, and Safari 10.1. 🚧

A connection has an object store set, 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.

A version change event will be fired at an open connection if an attempt is made to upgrade or delete the database. This gives the connection the opportunity to close to allow the upgrade or delete to proceed.

2.2. Object Store

An object store is the primary storage mechanism for storing data in a database.

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 upgradeneeded event. When a new database is created it doesn’t contain any object stores.

An object store has a list of records which hold the data stored in the object store. Each record 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 name, which is a name. At any one time, the name is unique within the database to which it belongs.

An object store optionally has a key path. If the object store has a key path it is said to use in-line keys. Otherwise it is said to use out-of-line keys.

An object store optionally has a key generator.

An object store can derive a key for a record from one of three sources:

A key generator. A key generator generates a monotonically increasing numbers every time a key is needed.
Keys can be derived via a key path.
Keys can also be explicitly specified when a value is stored in the object store.

2.2.1. Object Store Handle

Script does not interact with object stores directly. Instead, within a transaction, script has indirect access via an object store handle.

An object store handle has an associated object store and an associated transaction. 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 index set, which is initialized to the set of indexes that reference the associated 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 name, which is initialized to the name of the associated object store when the object store handle is created. The name will remain constant except when an upgrade transaction is running.

2.3. Values

Each record is associated with a value. User agents must support any serializable object. 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.

Record values are Records output by the StructuredSerializeForStorage operation.

2.4. Keys

In order to efficiently retrieve records stored in an indexed database, each record is organized according to its key.

A key has an associated type which is one of: number, date, string, binary, or array.

🚧 Binary keys are new in this edition. They are supported in Chrome 58, Firefox 51, and Safari 10.1. 🚧

A key also has an associated value, which will be either: an unrestricted double if type is number or date, a DOMString if type is string, a list of octets if type is binary, or a list of other keys if type is array.

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

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 can contain other arrays.

Attempting to convert other ECMAScript values to a key will fail.

An array key is a key with type array. The subkeys of an array key are the members of the array key's value list.

To compare two keys a and b, run these steps:

Let ta be the type of a.
Let tb be the type of b.
If ta is array and tb is binary, string, date or number, return 1.
If tb is array and ta is binary, string, date or number, return -1.
If ta is binary and tb is string, date or number, return 1.
If tb is binary and ta is string, date or number, return -1.
If ta is string and tb is date or number, return 1.
If tb is string and ta is date or number, return -1.
If ta is date and tb is number, return 1.
If tb is date and ta is number, return -1.
Assert: ta and tb are equal.
Let va be the value of a.
Let vb be the value of b.
Switch on ta:
number date
1. If va is greater than vb, then return 1.
2. If va is less than vb, then return -1.
3. Return 0.
string
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, then:
  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.
binary
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, then:
  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.
array
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, then:
  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.

The key a is greater than the key b if the result of running the steps to compare two keys with a and b is 1.

The key a is less than the key b if the result of running the steps to compare two keys with a and b is -1.

The key a is equal to the key b if the result of running the steps to compare two keys with a and b is 0.

As a result of the above rules, negative infinity is the lowest possible value for a key. Number keys are less than date keys. Date keys are less than string keys. String keys are less than binary keys. Binary keys are less than array 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. Members of binary keys are compared as unsigned octet values (in the range [0, 255]) rather than signed byte values (in the range [-128, 127]).

2.5. Key Path

A key path is a string or list of strings that defines how to extract a key from a value. A valid key path is one of:

An empty string.
An identifier, which is a string matching the IdentifierName production from the ECMAScript Language Specification [ECMA-262].
A string consisting of two or more identifiers separated by periods (U+002E FULL STOP).
A non-empty list containing only strings conforming to the above requirements.

Spaces are not allowed within a key path.

Key path values can only be accessed from properties explicitly copied by StructuredSerializeForStorage, as well as the following type-specific properties:

Type Properties Blob size, type File name, lastModified, lastModifiedDate Array length String length

2.6. Index

It is sometimes useful to retrieve records in an object store through other means than their key. An index allows looking up records in an object store using properties of the values in the object stores records.

An index is a specialized persistent key-value storage and has a referenced object store. The index has a list of records which hold the data stored in the index. The records 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 values in the index’s records are always values of keys in the index’s referenced object store. The keys are derived from the referenced object store’s values using a key path. If a given record with key X in the object store referenced by the index has the value A, and evaluating the index’s key path on A yields the result Y, then the index will contain a record with key Y and value X.

For example, if an index’s referenced object store contains a record with the key 123 and the value

{ name:
  "Alice", title: "CEO" }

, and the index’s key path is "name" then the index would contain a record with the key "Alice" and the value 123.

Records in an index are said to have a referenced value. 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.

In the preceding example, the record in the index with key "Alice" and value 123 would have a referenced value of

{ name: "Alice", title: "CEO"
  }

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

The records in an index are always sorted according to the 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 record's value (meaning the key of the record in the referenced object store).

An index has a name, which is a name. At any one time, the name is unique within index’s referenced object store.

An index has a unique flag. When this flag is set, the index enforces that no two records in the index has the same key. If a 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 multiEntry flag. This flag affects how the index behaves when the result of evaluating the index’s key path yields an array key. If the multiEntry flag is unset, then a single record whose key is an array key is added to the index. If the multiEntry flag is true, then the one record is added to the index for each of the subkeys.

2.6.1. Index Handle

Script does not interact with indexes directly. Instead, within a transaction, script has indirect access via an index handle.

An index handle has an associated index and an associated object store handle. The transaction of an index handle is the 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 name, which is initialized to the name of the associated index when the index handle is created. The name will remain constant except when an upgrade transaction is running.

2.7. Transactions

A Transaction 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.

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 connection.

A transaction has a scope 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 mode that determines which types of interactions can be performed upon that transaction. The mode is set when the transaction is created and remains fixed for the life of the transaction. A transaction's mode is one of the following:

"readonly" 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 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. "readwrite" 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 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. "versionchange" 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 upgradeneeded event is fired.

A transaction has an active flag, which determines if new requests can be made against the transaction. A transaction is said to be active if its active flag is set.

A transaction optionally has a cleanup event loop which is an event loop.

A transaction has a request list of requests which have been made against the transaction.

A transaction has a error which is set if the transaction is aborted.

A transaction's get the parent algorithm returns the transaction’s connection.

A read-only transaction is a transaction with mode "readonly".

A read/write transaction is a transaction with mode "readwrite".

2.7.1. Transaction Lifetime

Transactions are expected to be short lived. This is encouraged by the automatic committing functionality described below.

Authors can still cause transactions to run for a long time; however, this usage pattern is not advised as it can lead to a poor user experience.

The lifetime of a transaction is as follows:

A transaction is created with a scope and a mode. When a transaction is created its active flag is initially set.
The implementation must allow requests to be placed against the transaction whenever the active flag is set. This is the case even if the transaction has not yet been started. Until the transaction is 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 active. If an attempt is made to place a request against a transaction when that transaction is not active, the implementation must reject the attempt by throwing a "TransactionInactiveError" DOMException.
Once an implementation is able to enforce the constraints defined for the transaction scope and mode, defined below, the implementation must queue a task to start the transaction asynchronously.
Once the transaction has been 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 modes ensure that two requests placed against different transactions can execute in any order without affecting what resulting data is stored in the database.
A transaction can be aborted at any time before it is finished, even if the transaction isn’t currently active or hasn’t yet 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.
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 to abort 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.
When a transaction has been started and it can no longer become active, the implementation must attempt to commit it, as long as the transaction has not been 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 abort the transaction by following the steps to abort a transaction, otherwise it must commit the transaction by following the steps to commit a transaction.
When a transaction is committed or aborted, it is said to be finished. 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 abort the transaction.

The following constraints define when a transaction can be started:

Any number of read-only transactions are allowed to run concurrently, even if the transaction’s 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.
There are a number of ways that an implementation can ensure this. The implementation could prevent any read/write transaction, 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.
Similarly, implementations must ensure that a read/write transaction 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 read/write transaction’s scope. The implementation must also ensure that if the read/write transaction 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 read/write transactions are attempting to access the same object store (i.e. if they have overlapping scope), the transaction that was 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 finished.
Any transaction created after a read/write transaction must see the changes written by the read/write transaction. So if a read/write transaction, A, is created, and later another transaction B, is created, and the two transactions have overlapping scopes, then B must see any changes made to any object stores that are part of that overlapping 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 scope until the A transaction is finished.
Generally speaking, the above requirements mean that any transaction which has an overlapping scope with a read/write transaction and which was created after that read/write transaction, can’t run in parallel with that read/write transaction.
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 read/write transaction from starting.

To cleanup Indexed Database transactions, run these steps for each transaction with cleanup event loop matching the current event loop.

This behavior is invoked by [HTML52]. It ensures that transactions created by a script call to transaction() are deactivated once the task that invoked the script has completed. The steps are run at most once for each transaction.

2.7.2. Upgrade Transactions

An upgrade transaction is a transaction with mode "versionchange".

An upgrade transaction is automatically created when running the steps to run an upgrade transaction after a connection is opened to a database, if a version greater than the current version is specified. This transaction will be active inside the upgradeneeded event handler.

An upgrade transaction enables the creation, renaming, and deletion of object stores and indexes in a database.

An upgrade transaction is exclusive. The steps to open a database ensure that only one connection to the database is open when an upgrade transaction is running. The upgradeneeded 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 previous transactions are 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 by calling transaction() will throw an exception. Thus upgrade transactions not only ensure that no other transactions are running concurrently, but also ensure that no new transactions are queued against the same database as long as the transaction is running.

This ensures that once an upgrade transaction is complete, the set of object stores and indexes in a database remain constant for the lifetime of all subsequent connections and transactions.

2.8. Requests

Each asynchronous operation on a database is done using a request. Every request represents one operation.

A request has a done flag which is initially unset.

A request has a source object.

A request has a result and an error, neither of which are accessible until the done flag is set.

A request has a transaction which is initially null. This will be set when a request is placed against a transaction using the steps to asynchronously execute a request.

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

If an error occurs while performing the operation, the done flag is set, the error is set to the error, and an event with type error is fired at the request.

A request's get the parent algorithm returns the request’s transaction.

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 upgradeneeded event and final result of the open operation itself. In some cases, the request’s done flag will be unset then set again, and the result can change or error could be set insead.

2.8.1. Open Requests

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

The source of an open request is always null.

The transaction of an open request is null unless an upgradeneeded event has been fired.

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

Open requests are processed in a connection queue. The queue contains all open requests associated with an origin and a 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 close before the request can complete and allow further requests to be processed.

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.

2.9. Key Range

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

A key range has an associated lower bound (null or a key).

A key range has an associated upper bound (null or a key).

A key range has an associated lower open flag. Unless otherwise stated it is unset.

A key range has an associated upper open flag. 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 containing only key has both lower bound and upper bound equal to key.

A key is in a key range 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.

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.

An unbounded key range 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 convert a value to a key range with value and optional null disallowed flag are as follows:

If value is a key range, return value.
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.
Let key be the result of running the steps to convert a value to a key with value. Rethrow any exceptions.
If key is invalid, throw a "DataError" DOMException.
Return a key range containing only key.

2.10. Cursor

A cursor is used to iterate over a range of records in an index or an object store in a specific direction.

A cursor has a transaction, the transaction that was active when the cursor was created.

A cursor has a range of records in either an index or an object store.

A cursor has a source that indicates which index or an object store is associated with the records over which the cursor is iterating.

A cursor has a direction that determines whether it moves in monotonically increasing or decreasing order of the 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 source or at its end. A cursor’s direction is one of the following:

"next" This direction causes the cursor to be opened at the start of the source. When iterated, the cursor should yield all records, including duplicates, in monotonically increasing order of keys. "nextunique" This direction causes the cursor to be opened at the start of the 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 source is an object store or an index with the unique flag set, this direction has exactly the same behavior as "next". "prev" This direction causes the cursor to be opened at the end of the source. When iterated, the cursor should yield all records, including duplicates, in monotonically decreasing order of keys. "prevunique" This direction causes the cursor to be opened at the end of the 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 source is an object store or an index with the unique flag set, this direction has exactly the same behavior as "prev".

A cursor has a position within its range. It is possible for the list of records which the cursor is iterating over to change before the full range of the cursor has been iterated. In order to handle this, cursors maintain their 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 object store position, which indicates the value of the previously found record in the index. Both position and the object store position are used when finding the next appropriate record.

A cursor has a key and a value which represent the key and the value of the last iterated record.

A cursor has a got value flag. When this flag unset, the cursor is either in the process of loading the next value or it has reached the end of its 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 source of a cursor is an object store, the effective object store of the cursor is that object store and the effective key of the cursor is the cursor’s position. If the 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 key only flag, that indicates whether the cursor’s value is exposed via the API. Unless stated otherwise it is unset.

2.11. Key Generators

When a object store is created it can be specified to use a key generator. A key generator is used to generate keys for records inserted into an object store if not otherwise specified.

A key generator has a current number. The current number is always a positive integer less than or equal to 253 (9007199254740992) + 1. The initial value of a key generator's current number is 1, set when the associated object store is created. The current number is incremented as keys are generated, and may be updated to a specific value by using explicit keys.

Every object store that uses key generators uses a separate generator. That is, interacting with one object store never affects the key generator of any other object store.

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 record being stored with a key value specified in the call to store the record.

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

The current number for a key generator never decreases, other than as a result of database operations being reverted. Deleting a 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 clear() method, does not affect the current number of the object store’s key generator.

When a record is stored and a key is not specified in the call to store the record, a key is generated.

To generate a key for an object store store, run these steps:

Let generator be the key generator associated with store.
Let key be generator’s current number.
If key is greater than 253 (9007199254740992), then return failure.
Increase generator’s current number by 1.
Return key.

When a record is stored and a key is specified in the call to store the record, the associated key generator may be updated.

To possibly update the key generator for an object store store with key, run these steps:

If the type of key is not number, abort these steps.
Let value be the value of key.
Let value be the minimum of value and 253 (9007199254740992).
Let value be the largest integer not greater than value.
Let generator be the key generator associated with store.
If value is greater than or equal to generator’s current number, then set generator’s current number to value + 1.

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 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 record.

Only specified keys of type number can affect the current number of the key generator. Keys of type date, array (regardless of the other keys they contain), binary, or string (regardless of whether they could be parsed as numbers) have no effect on the current number of the key generator. Keys of type number with value less than 1 do not affect the current number since they are always lower than the current number.

When the current number of a key generator reaches above the value 253 (9007199254740992) any subsequent attempts to use the key generator to generate a new key will result in a "ConstraintError" DOMException. It is still possible to insert records into the object store by specifying an explicit key, however the only way to use a key generator again for such records is to delete the object store and create a new one.

This limit arises because integers greater than 9007199254740992 cannot be uniquely represented as ECMAScript Numbers. As an example, 9007199254740992 + 1 === 9007199254740992 in ECMAScript.

As long as key generators are used in a normal fashion this limit 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.

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.

Each object store gets its own key generator:

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

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

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

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

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

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.

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

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.

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

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 key path property.

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

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);
};

If the following conditions are true:

The object store has a key generator.
There is a value for the key path property.

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

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);
};

The following example illustrates the scenario when the specified in-line key is defined through a 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 key path for the object store is "foo.bar.baz". The actual object has no value for the foo property, { zip: {} }. When the object is saved in the object store the foo, bar, and baz properties are created each as a child of the other until a value for foo.bar.baz can be assigned. The value for foo.bar.baz is the next key generated by the object store.

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);
  };
};

Attempting to store a property on a primitive value will fail and throw an error. In the first example below the key path for the object store is "foo". The actual object is a primitive with the value, 4. 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, [10]. Trying to define a property on the array fails.

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

3. Exceptions

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 DOMExceptions used in this document along with a description of the exception type’s usage.

Type Description AbortError A request was aborted. ConstraintError A mutation operation in the transaction failed because a constraint was not satisfied. DataCloneError The data being stored could not be cloned by the internal structured cloning algorithm. DataError Data provided to an operation does not meet requirements. InvalidAccessError An invalid operation was performed on an object. InvalidStateError 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. NotFoundError The operation failed because the requested database object could not be found. QuotaExceededError 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. SyntaxError The keyPath argument contains an invalid key path. ReadOnlyError The mutating operation was attempted in a read-only transaction. TransactionInactiveError A request was placed against a transaction which is currently not active, or which is finished. UnknownError The operation failed for reasons unrelated to the database itself and not covered by any other errors. VersionError An attempt was made to open a database using a lower version than the existing version. 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.

4. API

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 task source for these tasks is the database access task source.

4.1. The `IDBRequest` interface

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

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.

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

var request = indexedDB.open('AddressBook', 15);
request.onsuccess = function(evt) {...};
request.onerror = function(evt) {...};

[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"
};

request . result When a request is completed, returns the result, or undefined if the request failed. Throws a "InvalidStateError" DOMException if the request is still pending. request . error When a request is completed, returns the error (a DOMException), or null if the request succeeded. Throws a "InvalidStateError" DOMException if the request is still pending. request . source Returns the IDBObjectStore, IDBIndex, or IDBCursor the request was made against, or null if is was an open request. request . transaction 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. request . readyState Returns "pending" until a request is complete, then returns "done".

The result attribute’s getter must throw an "InvalidStateError" DOMException if the done flag is unset. Otherwise, the attribute’s getter must return the result of the request, or undefined if the request resulted in an error.

The error attribute’s getter must throw an "InvalidStateError" DOMException if the done flag is unset. Otherwise, the attribute’s getter must return the error of the request, or null if no error occurred.

The source attribute’s getter must return the source of the request, or null if no source is set.

The transaction attribute’s getter must return the transaction of the request. This property can be null for certain requests, such as for requests returned from open().

The readyState attribute’s getter must return "pending" if the done flag is unset, and "done" otherwise.

The onsuccess attribute is the event handler for the success event.

The onerror attribute is the event handler for the error event.

Methods on IDBDatabase that return a open request use an extended interface to allow listening to the blocked event and upgradeneeded event.

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

The onblocked attribute is the event handler for the blocked event.

The onupgradeneeded attribute is the event handler for the upgradeneeded event.

4.2. Event interfaces

This specification fires events with the following custom interfaces:

[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;
};

The oldVersion attribute getter returns the previous version of the database.

The newVersion attribute getter returns the new version of the database, or null if the database is being deleted. See the steps to run an upgrade transaction.

Events are constructed as defined in Constructing events, in [DOM41].

To fire a version change event named e at target given oldVersion and newVersion, run these steps:

Let event be the result of creating an event using IDBVersionChangeEvent.
Set event’s type attribute to e.
Set event’s bubbles and cancelable attributes to false.
Set event’s oldVersion attribute to oldVersion.
Set event’s newVersion attribute to newVersion.
Let legacyOutputDidListenersThrowFlag be unset.
Dispatch event at target with legacyOutputDidListenersThrowFlag.
Return legacyOutputDidListenersThrowFlag.
The return value of this algorithm is not always used.

4.3. The `IDBFactory` interface

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.

partial interface WindowOrWorkerGlobalScope {
  [SameObject] readonly attribute IDBFactory indexedDB;
};

The indexedDB attribute provides applications a mechanism for accessing capabilities of indexed databases.

[Exposed=(Window,Worker)]
interface IDBFactory {
  [NewObject] IDBOpenDBRequest open(DOMString name,
                                    optional [EnforceRange] unsigned long long version);
  [NewObject] IDBOpenDBRequest deleteDatabase(DOMString name);

  short cmp(any first, any second);
};

request = indexedDB . open(name) 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 result will be the connection. request = indexedDB . open(name, version) 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 versionchange event, the request will be 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 result will be the connection. request = indexedDB . deleteDatabase(name) Attempts to delete the named database. If the database already exists and there are open connections that don’t close in response to a versionchange event, the request will be blocked until all they close. If the request is successful request’s result will be null.

The open(name, version) method, when invoked, must run these steps:

If version is 0 (zero), throw a TypeError.
Let origin be the origin of the global scope used to access this IDBFactory.
If origin is an opaque origin, throw a "SecurityError" DOMException and abort these steps.
Let request be a new open request.
Run these steps in parallel:
1. Let result be the result of running the steps to open a database, with origin, name, version if given and undefined otherwise, and request.
  What happens if version is not given? If version is not given and a database with that name already exists, a connection will be opened without changing the version. If version is not given and no database with that name exists, a new database will be created with version equal to 1.
2. Queue a task to run these steps:
  1. If result is an error, set request’s result to undefined, set request’s error to result, set request’s done flag, and fire an event named error at request with its bubbles and cancelable attributes initialized to true.
  2. Otherwise, set request’s result to result, set request’s done flag, and fire an event named success at request. If the steps above resulted in an upgrade transaction being run, then firing the "success" event must be done after the upgrade transaction completes.
    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 versionchange event. Why aren’t the steps to fire a success event or fire an error event used? There is no transaction associated with the request (at this point), so those steps — which activate an associated transaction before dispatch and deactivate the transaction after dispatch — do not apply.
Return a new IDBOpenDBRequest object for request.

The deleteDatabase(name) method, when invoked, must run these steps:

Let origin be the origin of the global scope used to access this IDBFactory.
If origin is an opaque origin, throw a "SecurityError" DOMException and abort these steps.
Let request be a new open request.
Run these steps in parallel:
1. Let result be the result of running the steps to delete a database, with origin, name, and request.
2. Queue a task to run these steps:
  1. If result is an error, set request’s error to result, set request’s done flag, and fire an event named error at request with its bubbles and cancelable attributes initialized to true.
  2. Otherwise, set request’s result to undefined, set request’s done flag, and fire a version change event named success at request with result and null.
    Why aren’t the steps to fire a success event or fire an error event used? There is no transaction associated with the request, so those steps — which activate an associated transaction before dispatch and deactivate the transaction after dispatch — do not apply.
Return a new IDBOpenDBRequest object for request.

result = indexedDB . cmp(key1, key2) 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.

The cmp(first, second) method, when invoked, must run these steps:

Let a be the result of running the steps to convert a value to a key with first. Rethrow any exceptions.
If a is invalid, throw a "DataError" DOMException.
Let b be the result of running the steps to convert a value to a key with second. Rethrow any exceptions.
If b is invalid, throw a "DataError" DOMException.
Return the results of running the steps to compare two keys with a and b.

4.4. The `IDBDatabase` interface

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 abort, error, or versionchange. If an IDBDatabase object is garbage collected, the associated connection must be closed.

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

  [NewObject] IDBTransaction transaction((DOMString or sequence<DOMString>) storeNames,
                                         optional IDBTransactionMode mode = "readonly");
  void close();

  [NewObject] 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<DOMString>)? keyPath = null;
  boolean autoIncrement = false;
};

connection . name Returns the name of the database. connection . version Returns the version of the database.

The name attribute’s getter must return the 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 version attribute’s getter must return this connection's version.

Is this the same as the database's version? As long as the connection is open, this is the same as the connected database's version. But once the connection has closed, this attribute will not reflect changes made with a later upgrade transaction.

connection . objectStoreNames Returns a list of the names of object stores in the database. store = connection . createObjectStore(name [, options]) 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.

connection . deleteObjectStore(name) Deletes the object store with the given name.

Throws a "InvalidStateError" DOMException if not called within an upgrade transaction.

The objectStoreNames attribute’s getter must return a DOMStringList associated with a sorted name list of the names of the object stores in this connection's object store set.

Is this the same as the database's object store names? As long as the connection is open, this is the same as the connected database's object store names. But once the connection has closed, this attribute will not reflect changes made with a later upgrade transaction.

The createObjectStore(name, options) method, when invoked, must run these steps:

Let database be the database associated with this connection.
Let transaction be database’s upgrade transaction if it is not null, or throw an "InvalidStateError" DOMException otherwise.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
Let keyPath be options’s keyPath member if it is not undefined or null, or null otherwise.
If keyPath is not null and is not a valid key path, throw a "SyntaxError" DOMException.
If an object store named name already exists in database throw a "ConstraintError" DOMException.
Let autoIncrement be set if options’s autoIncrement member is true, or unset otherwise.
If autoIncrement is set and keyPath is an empty string or any sequence (empty or otherwise), throw an "InvalidAccessError" DOMException.
Let store be a new object store in database. Set the created object store's 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 key path to keyPath.
Return a new object store handle associated with store and transaction.

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 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 to abort 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 deleteObjectStore(name) method, when invoked, must run these steps:

Let database be the database associated with this connection.
Let transaction be database’s upgrade transaction if it is not null, or throw an "InvalidStateError" DOMException otherwise.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
Let store be the object store named name in database, or throw a "NotFoundError" DOMException if none.
Remove store from this connection's object store set.
If there is an object store handle associated with store and transaction, remove all entries from its index set.
Destroy store.

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 objectStoreNames property on the IDBDatabase instance on which it was called.

transaction = connection . transaction(scope [, mode = "readonly"]) Returns a new transaction with the given mode ("readonly" or "readwrite") and scope which can be a single object store name or an array of names. connection . close() Closes the connection once all running transactions have finished.

The transaction(storeNames, mode) method, when invoked, must run these steps:

If a running upgrade transaction is associated with the connection, throw an "InvalidStateError" DOMException.
If the connection's close pending flag is set, throw an "InvalidStateError" DOMException.
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.
If any string in scope is not the name of an object store in the connected database, throw a "NotFoundError" DOMException.
If scope is empty, throw an "InvalidAccessError" DOMException.
If mode is not "readonly" or "readwrite", throw a TypeError.
Let transaction be a newly created transaction with connection, mode and the set of object stores named in scope.
Set transaction’s cleanup event loop to the current event loop.
Return an IDBTransaction object representing transaction.

The created transaction will follow the lifetime rules.

The close() method, when invoked, must run these steps:

The onabort attribute is the event handler for the abort event.

The onclose attribute is the event handler for the close event.

🚧 The onclose attribute is new in this edition. It is supported in Chrome 31, Firefox 50, and Safari 10.1. 🚧

The onerror attribute is the event handler for the error event.

The onversionchange attribute is the event handler for the versionchange event.

4.5. The `IDBObjectStore` interface

The IDBObjectStore interface represents an object store handle.

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

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

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

  IDBIndex index(DOMString name);

  [NewObject] IDBIndex createIndex(DOMString name,
                                   (DOMString or sequence<DOMString>) keyPath,
                                   optional IDBIndexParameters options);
  void deleteIndex(DOMString name);
};

dictionary IDBIndexParameters {
  boolean unique = false;
  boolean multiEntry = false;
};

store . name Returns the name of the store. store . name = newName Updates the name of the store to newName.

Throws "InvalidStateError" DOMException if not called within an upgrade transaction.

store . keyPath Returns the key path of the store, or null if none. list . indexNames Returns a list of the names of indexes in the store. store . transaction Returns the associated transaction. store . autoIncrement Returns true if the store has a key generator, and false otherwise.

The name attribute’s getter must return this object store handle's name.

Is this the same as the object store's name? As long as the transaction has not finished, this is the same as the associated object store's name. But once the transaction has finished, this attribute will not reflect changes made with a later upgrade transaction.

The name attribute’s setter must run these steps:

🚧 The name attribute’s setter is new in this edition. It is supported in Chrome 58, Firefox 51, and Safari 10.1. 🚧

The keyPath attribute’s getter must return this object store handle's object store's key path, or null if none. The key path is converted as a DOMString (if a string) or a sequence<DOMString> (if a list of strings), per [WEBIDL].

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 indexNames attribute’s getter must return a DOMStringList associated with a sorted name list of the names of indexes in this object store handle's index set.

Is this the same as object store's list of index names? As long as the transaction has not finished, this is the same as the associated object store's list of index names. But once the transaction has finished, this attribute will not reflect changes made with a later upgrade transaction.

The transaction attribute’s getter must return this object store handle's transaction.

The autoIncrement attribute’s getter must return true if this object store handle's object store has a key generator, and false otherwise.

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 active. request = store . put(value [, key]) request = store . add(value [, key]) Adds or updates a record in store with the given value and key.

If the store uses in-line keys and key is specified a "DataError" DOMException will be thrown.

If put() is used, any existing record with the key will be replaced. If add() is used, and if a record with the key already exists the request will fail, with request’s error set to a "ConstraintError" DOMException.

If successful, request’s result will be the record's key.

request = store . delete(query) Deletes records in store with the given key or in the given key range in query.

If successful, request’s result will be undefined.

request = store . clear() Deletes all records in store.

If successful, request’s result will be undefined.

The put(value, key) method, when invoked, must run these steps:

Let transaction be this object store handle's transaction.
Let store be this object store handle's object store.
If store has been deleted, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
If transaction is a read-only transaction, throw a "ReadOnlyError" DOMException.
If store uses in-line keys and key was given, throw a "DataError" DOMException.
If store uses out-of-line keys and has no key generator and key was not given, throw a "DataError" DOMException.
If key was given, then:
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.
Let targetRealm be a user-agent defined Realm.
Let clone be a clone of value in targetRealm. Rethrow any exceptions.
Why create a copy of the value? The value is be serialized when stored. Treating it as a copy here allows other algorithms in this specification to treat it as an ECMAScript value, but implementations can optimize this if the difference in behavior is not observable.
If store uses in-line keys, then:
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 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 (kpk is failure):
Run the steps to asynchronously execute 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 store a record into an object store as operation, using store, the clone as value, key, and with the no-overwrite flag unset.

The add(value, key) method, when invoked, must run these steps:

Let transaction be this object store handle's transaction.
Let store be this object store handle's object store.
If store has been deleted, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
If transaction is a read-only transaction, throw a "ReadOnlyError" DOMException.
If store uses in-line keys and key was given, throw a "DataError" DOMException.
If store uses out-of-line keys and has no key generator and key was not given, throw a "DataError" DOMException.
If key was given, then:
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.
Let targetRealm be a user-agent defined Realm.
Let clone be a clone of value in targetRealm. Rethrow any exceptions.
Why create a copy of the value? The value is serialized when stored. Treating it as a copy here allows other algorithms in this specification to treat it as an ECMAScript value, but implementations can optimize this if the difference in behavior is not observable.
If store uses in-line keys, then:
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 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 (kpk is failure):
Run the steps to asynchronously execute 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 store a record into an object store as operation, using store, clone as value, key, and with the no-overwrite flag set.

The delete(query) method, when invoked, must run these steps:

Let transaction be this object store handle's transaction.
Let store be this object store handle's object store.
If store has been deleted, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
If transaction is a read-only transaction, throw a "ReadOnlyError" DOMException.
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.
Run the steps to asynchronously execute 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 delete records from an object store as operation, using store and range.

The query parameter may be a key or an IDBKeyRange identifying the records keys to be deleted.

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

The clear() method, when invoked, must run these steps:

The following methods throw a "TransactionInactiveError" DOMException if called when the transaction is not active. request = store . get(query) Retrieves the value of the first record matching the given key or key range in query.

If successful, request’s result will be the value, or undefined if there was no matching record.

request = store . getKey(query) Retrieves the key of the first record matching the given key or key range in query.

If successful, request’s result will be the key, or undefined if there was no matching record.

request = store . getAll(query [, count]) Retrieves the values of the records matching the given key or key range in query (up to count if given).

If successful, request’s result will be an Array of the values.

request = store . getAllKeys(query [, count]) Retrieves the keys of records matching the given key or key range in query (up to count if given).

If successful, request’s result will be an Array of the keys.

request = store . count(query) Retrieves the number of records matching the given key or key range in query.

If successful, request’s result will be the count.

The get(query) method, when invoked, must run these steps:

Let transaction be this object store handle's transaction.
Let store be this object store handle's object store.
If store has been deleted, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
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.
Run the steps to asynchronously execute 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 retrieve a value from an object store as operation, using the current Realm as targetRealm, store and range.

The query parameter may be a key or an IDBKeyRange identifying the record to be retrieved. If a range is specified, the method retrieves the first existing value in that range.

This method produces the same result if a record with the given key doesn’t exist as when a record exists, but has undefined as value. If you need to tell the two situations apart, you can use openCursor() with the same key. This will return a cursor with undefined as value if a record exists, or no cursor if no such record exists.

The getKey(query) method, when invoked, must run these steps:

Let transaction be this object store handle's transaction.
Let store be this object store handle's object store.
If store has been deleted, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
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.
Run the steps to asynchronously execute 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 retrieve a key from an object store as operation, using store and range.

The query parameter may be a key or an IDBKeyRange identifying the record key to be retrieved. If a range is specified, the method retrieves the first existing key in that range.

🚧 The getKey() method on IDBObjectStore is new in this edition. It is supported in Chrome 58, Firefox 51, and Safari 10.1. 🚧

The getAll(query, count) method, when invoked, must run these steps:

Let transaction be this object store handle's transaction.
Let store be this object store handle's object store.
If store has been deleted, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
Let range be the result of running the steps to convert a value to a key range with query. Rethrow any exceptions.
Run the steps to asynchronously execute 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 retrieve multiple values from an object store as operation, using the current Realm as targetRealm, store, range, and count if given.

The query parameter may be a key or an IDBKeyRange identifying the 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.

🚧 The getAll() method is new in this edition. It is supported in Chrome 48, Firefox 44, and Safari 10.1. 🚧

The getAllKeys(query, count) method, when invoked, must run these steps:

Let transaction be this object store handle's transaction.
Let store be this object store handle's object store.
If store has been deleted, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
Let range be the result of running the steps to convert a value to a key range with query. Rethrow any exceptions.
Run the steps to asynchronously execute 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 retrieve multiple keys from an object store as operation, using store, range, and count if given.

The query parameter may be a key or an IDBKeyRange identifying the 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.

🚧 The getAllKeys() method is new in this edition. It is supported in Chrome 48, Firefox 44, and Safari 10.1. 🚧

The count(query) method, when invoked, must run these steps:

Let transaction be this object store handle's transaction.
Let store be this object store handle's object store.
If store has been deleted, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
Let range be the result of running the steps to convert a value to a key range with query. Rethrow any exceptions.
Run the steps to asynchronously execute 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.

The query parameter may be a key or an IDBKeyRange identifying the records keys to be counted. If null or not given, an unbounded key range is used.

The following methods throw a "TransactionInactiveError" DOMException if called when the transaction is not active. request = store . openCursor([query [, direction = "next"]]) Opens a cursor over the records matching query, ordered by direction. If query is null, all records in store are matched.

If successful, request’s result will be an IDBCursorWithValue pointing at the first matching record, or null if there were no matching records.

request = store . openKeyCursor([query [, direction = "next"]]) Opens a cursor with key only flag set over the records matching query, ordered by direction. If query is null, all records in store are matched.

If successful, request’s result will be an IDBCursor pointing at the first matching record, or null if there were no matching records.

The openCursor(query, direction) method, when invoked, must run these steps:

Let transaction be this object store handle's transaction.
Let store be this object store handle's object store.
If store has been deleted, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
Let range be the result of running the steps to convert a value to a key range with query. Rethrow any exceptions.
Let cursor be a new cursor with transaction set to transaction, an undefined position, direction set to direction, got value flag unset, and undefined key and value. The source of cursor is store. The range of cursor is range.
Run the steps to asynchronously execute 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 iterate a cursor as operation, using the current Realm as targetRealm, and cursor.

The query parameter may be a key or an IDBKeyRange to use as the cursor's range. If null or not given, an unbounded key range is used.

The openKeyCursor(query, direction) method, when invoked, must run these steps:

Let transaction be this object store handle's transaction.
Let store be this object store handle's object store.
If store has been deleted, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
Let range be the result of running the steps to convert a value to a key range with query. Rethrow any exceptions.
Let cursor be a new cursor with transaction set to transaction, an undefined position, direction set to direction, got value flag unset, and undefined key and value. The source of cursor is store. The range of cursor is range. The key only flag of cursor is set.
Run the steps to asynchronously execute 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 iterate a cursor as operation, using the current Realm as targetRealm, and cursor.

The query parameter may be a key or an IDBKeyRange to use as the cursor's range. If null or not given, an unbounded key range is used.

🚧 The openKeyCursor() method is new in this edition. It is supported in Chrome 48, Firefox 44, and Safari 10.1. 🚧

index = store . index(name) Returns an IDBIndex for the index named name in store. index = store . createIndex(name, keyPath [, options]) 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 abort with a "ConstraintError" DOMException.

Throws an "InvalidStateError" DOMException if not called within an upgrade transaction.

store . deleteIndex(name) Deletes the index in store with the given name.

Throws an "InvalidStateError" DOMException if not called within an upgrade transaction.

The createIndex(name, keyPath, options) method, when invoked, must run these steps:

Let transaction be this object store handle's transaction.
Let store be this object store handle's object store.
If transaction is not an upgrade transaction, throw an "InvalidStateError" DOMException.
If store has been deleted, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
If an index named name already exists in store, throw a "ConstraintError" DOMException.
If keyPath is not a valid key path, throw a "SyntaxError" DOMException.
Let unique be set if options’s unique member is true, and unset otherwise.
Let multiEntry be set if options’s multiEntry member is true, and unset otherwise.
If keyPath is a sequence and multiEntry is set, throw an "InvalidAccessError" DOMException.
Let index be a new index in store. Set index’s name to name and key path to keyPath. If unique is set, set index’s unique flag. If multiEntry is set, set index’s multiEntry flag.
Add index to this object store handle's index set.
Return a new index handle associated with index and this object store handle.

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 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 createIndex() call.

This method synchronously modifies the 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 to abort 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.

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

var request1 = objectStore.put({name: "betty"}, 1);
var request2 = objectStore.put({name: "betty"}, 2);
var index = objectStore.createIndex("by_name", "name", {unique: true});

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 uniqueness constraint does not cause the second request to fail. Instead, the transaction will be aborted when the index is created and the constraint fails.

The index(name) method, when invoked, must run these steps:

Each call to this method on the same IDBObjectStore instance with the same name returns the same IDBIndex instance. 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.

The deleteIndex(name) method, when invoked, must run these steps:

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

4.6. The `IDBIndex` interface

The IDBIndex interface represents an index handle.

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

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

  [NewObject] IDBRequest openCursor(optional any query,
                                    optional IDBCursorDirection direction = "next");
  [NewObject] IDBRequest openKeyCursor(optional any query,
                                       optional IDBCursorDirection direction = "next");
};

index . name Returns the name of the index. index . name = newName Updates the name of the store to newName.

Throws an "InvalidStateError" DOMException if not called within an upgrade transaction.

index . objectStore Returns the IDBObjectStore the index belongs to. index . keyPath Returns the key path of the index. index . multiEntry Returns true if the index’s multiEntry flag is set. index . unique Returns true if the index’s unique flag is set.

The name attribute’s getter must return this index handle's name.

Is this the same as the index's name? As long as the transaction has not finished, this is the same as the associated index's name. But once the transaction has finished, this attribute will not reflect changes made with a later upgrade transaction.

The name attribute’s setter must run these steps:

Let name be the given value.
Let transaction be this index handle's transaction.
Let index be this index handle's index.
If transaction is not an upgrade transaction, throw an "InvalidStateError" DOMException.
If transaction is not active, throw a "TransactionInactiveError" DOMException.
If index or index’s object store has been deleted, throw an "InvalidStateError" DOMException.
If index’s name is equal to name, terminate these steps.
If an index named name already exists in index’s object store, throw a "ConstraintError" DOMException.
Set index’s name to name.
Set this index handle's name to name.

🚧 The name attribute’s setter is new in this edition. It is supported in Chrome 58, Firefox 51, and Safari 10.1. 🚧

The objectStore attribute’s getter must return this index handle's object store handle.

The keyPath attribute’s getter must return this index handle's index's key path. The key path is converted as a DOMString (if a string) or a sequence<DOMString> (if a list of strings), per [WEBIDL].

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 multiEntry attribute’s getter must return true if this index handle's index's multiEntry flag is set, and false otherwise.

The unique attribute’s getter must return true if this index handle's index's unique flag is set, and false otherwise.

The following methods throw an "TransactionInactiveError" DOMException if called when the transaction is not active. request = store . get(query) Retrieves the value of the first record matching the given key or key range in query.