3.1.1 Database

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

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

Every database has a name which identifies it within a specific origin. The name can be any string value, including the empty string, and stays constant for the lifetime of the database. Each database also has a current version. When a database is first created, its version is 0.

Databases has a delete pending flag which is used during deletion. When a database is requested to be deleted the flag is set to true and all attempts at opening the database are stalled until the database can be deleted.

The act of opening a database creates a connection. There MAY be multiple connections to a given database at any given time. Each connection has a closePending flag which initially is set to false.

When a connection is initially created it is in opened state. The connection can be closed through several means. If the connection is GCed or execution context where the connection is created is destroyed (for example due to the user navigating away from that page), the connection is closed. The connection can also be closed explicitly using the steps for closing a database connection. When the connection is closed the closePending flag is always set to true if it hasn't already been.

The IDBDatabase interface represents a connection to a database.

3.1.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 can only be changed using a "versionchange" transaction, i.e. in response to a upgradeneeded event. When a new database is created it doesn't contain any object stores.

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

Every object store has a name. The name is unique within the database to which it belongs. Every object store also optionally has a key generator and an optional 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.

The object store can derive the key from one of three sources:

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

The IDBObjectStore interface represents an object store. Note however that multiple instances of those interfaces representing the same object store can exist.

3.1.3 Keys

In order to efficiently retrieve records stored in an indexed database, each record is organized according to its key. A value is said to be a valid key if it is one of the following ECMAScript [ECMA-262] types: Number primitive value, String primitive value, Date object, or Array object. An Array is only a valid key if every item in the array is defined and is a valid key (i.e. sparse arrays can not be valid keys) and if the Array doesn't directly or indirectly contain itself. Any non-numeric properties on an Array are ignored, and thus do not affect whether the Array is a valid key. If the value is of type Number, it is only a valid key if it is not NaN. If the value is of type Date it is only a valid key if its [[PrimitiveValue]] internal property, as defined by [ECMA-262], is not NaN. Conforming user agents MUST support all valid keys as keys.

Operations that accept keys MUST perform as if each key parameter value, in order, is copied by the structured clone algorithm [HTML5] and the copy is instead used as input to the operation, before proceding with rest of the operation.

For purposes of comparison, all Arrays are greater than all String, Date and Number values; all String values are greater than all Date and Number values; and all Date values are greater than all Number values. Values of type Number are compared to other Number values numerically. Values of type Date are compared to other Date values chronologically. Values of type String are compared to other values of type String by using the algorithm defined by step 4 of section 11.8.5, The Abstract Relational Comparison Algorithm, of the ECMAScript Language Specification [ECMA-262]. Values of type Array are compared to other values of type Array as follows:

1. Let A be the first Array value and B be the second Array value.
2. Let length be the lesser of A's length and B's length.
3. Let i be 0.
4. If the ith value of A is less than the ith value of B, then A is less than B. Skip the remaining steps.
5. If the ith value of A is greater than the ith value of B, then A is greater than B. Skip the remaining steps.
6. Increase i by 1.
7. If i is not equal to length, go back to step 4. Otherwise continue to next step.
8. If A's length is less than B's length, then A is less than B. If A's length is greater than B's length, then A is greater than B. Otherwise A and B are equal.

The terms greater than, less than and equal to are defined in the terms of the above comparisons.

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.

3.1.4 Values

Each record is associated with a value. Conforming user agents MUST support any ECMAScript [ECMA-262] value supported by the structured clone algorithm [HTML5]. 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.

3.1.5 Key Path

A key path is a DOMString or sequence<DOMString> that defines how to extract a key from a value. A valid key path is one of:

• An empty DOMString.
• An identifier, which is a DOMString matching the IdentifierName production from the ECMAScript Language Specification [ECMA-262].
• A DOMString consisting of two or more identifiers separated by periods (ASCII character code 46).
• A non-empty sequence<DOMString> containing only DOMStrings conforming to the above requirements.

To evaluate a key path, run the steps for extracting a key from a value using a key path.

Key path values can only be accessed from properties explicitly copied by the structured clone algorithm, as well as the following properties:

• Blob.size
• Blob.type
• File.name
• File.lastModifiedDate
• Array.length
• String.length

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

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.

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

Every index has a name. The name is unique within index's referenced object store.

Each index also has a unique flag. When this flag is set to true, 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.

Each index also has a multiEntry flag. This flag affects how the index behaves when the result of evaluating the index's key path yields an Array. If the multiEntry flag is false, then a single record whose key is an Array is added to the index. If the multiEntry flag is true, then the one record is added to the index for each item in the Array. The key for each record is the value of respective item in the Array.

The IDBIndex interface provides access to the metadata of an index. Note however that multiple instances of those interfaces representing the same index can exist.

3.1.7 Transaction

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.

All transactions are created through a connection, which is the transaction's connection. The 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. The transaction also has a scope that determines the object stores with which the transaction may interact. Transactions have an active flag, which determines if new requests can be made against the transaction. Finally, transactions also contain a request list of requests which have been made against the transaction.

Each transaction has a fixed scope, determined when the transaction is created. A transaction's scope remains fixed for the lifetime of that 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.

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 generally recommended as it can lead to a bad user experience.

The lifetime of a transaction is as follows:

1. A transaction is created using IDBDatabase.transaction. The arguments passed determine the scope of the transaction and whether the transaction is read-only. When a transaction is created its active flag is initially set to true.
2. The implementation MUST allow requests to be placed against the transaction whenever the active flag is true. 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 DOMException of type TransactionInactiveError.
3. Once an implementation is able to enforce the constraints defined for the transaction mode, defined below, the implementation MUST queue up an operation to start the transaction asynchronously. The timing for when this happens is affected by:
   • The mode in which the transaction is opened.
   • Which object stores are included in the scope of the transaction.
4. 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.
5. 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.
6. A transaction can fail for reasons not tied to a particular IDBRequest. For example due to IO errors when committing the transaction, or due to running into a quota limit where the implementation can't tie exceeding the quota to a partcular request. In this case the implementation MUST run the steps for aborting a transaction using the transaction as transaction and the appropriate error type as error. For example if quota was exceeded then QuotaExceededError should be used as error, and if an IO error happened, UnknownError should be used as error.
7. When a transaction 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 for aborting a transaction, otherwise it MUST commit the transaction by following the steps for committing a transaction.
8. 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.

Transactions are opened in one of three modes. The mode determines how concurrent access to object stores in the transaction are isolated.

enum IDBTransactionMode {
    "readonly",
    "readwrite",
    "versionchange"
};

Any number of transactions opened in "readonly" mode are allowed to run concurrently, even if the transaction's scope overlap and include the same object stores. As long as a "readonly" 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 ensures this. The implementation can prevent any "readwrite" transaction, whose scope overlaps the scope of the "readonly" transaction, from starting until the "readonly" transaction finishes. Or the implementation can allow the "readonly" transaction to see a snapshot of the contents of the object stores which is taken when the "readonly" transaction started.

Similarly, implementations MUST ensure that a "readwrite" 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 "readwrite" transaction's scope. The implementation MUST also ensure that if the "readwrite" 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 "readwrite" 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 "readwrite" transaction MUST see the changes written by the "readwrite" transaction. So if a "readwrite" 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.

A "versionchange" transaction never run concurrently with other transactions. When a database is opened with a version number higher than the current version, a new "versionchange" transaction is automatically created and made available through the upgradeneeded event. The upgradeneeded event isn't fired, and thus the "versionchange" transaction isn't started, until all other connections to the same database are closed. This ensures that all other transactions are finished.

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

User agents MUST ensure a reasonable level of fairness across transactions to prevent starvation. For example, if multiple "readonly" transactions are started one after another the implementation MUST NOT indefinitely prevent a pending "readwrite" transaction from starting.

Each transaction object implement the IDBTransaction interface.

3.1.8 Requests

Each reading and writing operation on a database is done using a request. Every request represents one read or write operation. Requests have a done flag which initially is false, and a source object. Every request also has a result and an error attribute, neither of which are accessible until the done flag is set to true.

Finally, requests have a request transaction. When a request is created, it is always placed against a transaction using the steps for asynchronously executing a request. The steps set the request transaction to be that transaction. The steps do not set the request transaction to be that request for the request returned from an IDBFactory.open call however. That function create requests which have a null request transaction.

enum IDBRequestReadyState {
    "pending",
    "done"
};

3.1.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 MAY be lower-bounded or upper-bounded (there is a value that is, respectively, smaller than or larger than all its elements). A key range is said to be bounded if it is both lower-bounded and upper-bounded. If a key range is neither lower-bounded nor upper-bounded it is said to be unbounded. A key range MAY be open (the key range does not include its endpoints) or closed (the key range includes its endpoints). A key range MAY consist of a single value.

The IDBKeyRange interface defines a key range.

interface IDBKeyRange {
    readonly    attribute any     lower;
    readonly    attribute any     upper;
    readonly    attribute boolean lowerOpen;
    readonly    attribute boolean upperOpen;
    static IDBKeyRange only (any value);
    static IDBKeyRange lowerBound (any lower, optional boolean open = false);
    static IDBKeyRange upperBound (any upper, optional boolean open = false);
    static IDBKeyRange bound (any lower, any upper, optional boolean lowerOpen = false, optional boolean upperOpen = false);
};

A key is in a key range if both the following conditions are fulfilled:

• The key range lower value is undefined or less than key. It may also be equal to key if lowerOpen is false.
• The key range upper value is undefined or greater than key. It may also be equal to key if upperOpen is false.

3.1.10 Cursor

Cursors are a transient mechanism used to iterate over multiple records in a database. Storage operations are performed on the underlying index or an object store.

A cursor comprises a range of records in either an index or an object store. The cursor has a source that indicates which index or object store is associated with the records over which the cursor is iterating. A cursor maintains a position over this series, which moves in a direction that is in either monotonically increasing or decreasing order of the record keys. Cursors also have a key and a value which represent the key and the value of the last iterated record. Cursors finally have a got value flag. When this flag is false, the cursor is either in the process of loading the next value or it has reached the end of its range, when it is true, it indicates that the cursor is currently holding a value and that it is ready to iterate to the next one.

There are four possible values for a cursor's direction. The direction of a cursor determines if the cursor initial position is at the start of its source or at its end. It also determines in which direction the cursor moves when iterated, and if it skips duplicated values when iterating indexes. The allowed values for a cursor's direction is as follows:

enum IDBCursorDirection {
    "next",
    "nextunique",
    "prev",
    "prevunique"
};

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.

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.

Cursor objects implement the IDBCursor interfaces. There is only ever one IDBCursor instance representing a given cursor. However there is no limit on how many cursors can be used at the same time.

3.1.11 Exceptions

Each of the exceptions defined in the IndexedDB spec is a DOMException with a specific type. [DOM4] Existing DOM Level 4 exceptions will set their code to a legacy value; however, the new indexedDB type exceptions will have a code value of 0. The message value is optional.

IndexedDB uses the following new DOMException types with their various messages. All of these new types will have a code value of 0 zero.

IndexedDB reuses the following existing DOMException types from [DOM4]. These types will continue to return the codes and names as specified in DOM4; however, they will have the following messages when thrown from an IndexedDB API:

3.1.12 Options Object

Options objects are dictionary objects [WEBIDL] which are used to supply optional parameters to some indexedDB functions like createObjectStore and createIndex. The attributes on the object correspond to optional parameters on the function called.

The following WebIDL defines IDBObjectStoreParameters dictionary type.

dictionary IDBObjectStoreParameters {
    (DOMString or sequence<DOMString>)? keyPath = null;
    boolean                             autoIncrement = false;
};

The following WebIDL defines IDBIndexParameters dictionary type.

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

The following WebIDL defines IDBVersionChangeEventInit dictionary type.

dictionary IDBVersionChangeEventInit : EventInit {
    unsigned long long  oldVersion = 0;
    unsigned long long? newVersion = null;
};

3.1.13 Key Generators

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

• Every object store that uses key generators use a separate generator. I.e. interacting with one object store never affects the key generator of any other object store.
• The current number of a key generator is always set to 1 when the object store for that key generator is first created.
• When a key generator is used to generate a new key for a object store, the key generator's current number is used as the new key value and then the key generator's current number is increased by 1.

• When a record is stored and an key value is specified in the call to store the record, if the specified key value is a Number greater than or equal to the key generator's current number, then the key generator's current number is set to the smallest integer number greater than the explicit key. A key can be specified both for object stores which use in-line keys, by setting the property on the stored value which the object store's 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 values which are Number values affect the current number of the key generator. Dates and Arrays which contain Numbers do not affect the current number of the key generator. Nor do DOMString values which could be parsed as numbers. Negative Numbers do not affect the current number since they are always lower than the current number.

• 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's for all object stores in the transaction's scope is reverted to the values they had before the transaction was started.
• When the current number of a key generator reaches above the value 2^53 (9007199254740992) any attempts to use the key generator to generate a new key will result in a ConstraintError. 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 the object store is to delete the object store and create a new one.
  Note

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

• 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() function, does not affect the current number of the object store's key generator.

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

3.2.1 The IDBRequest Interface

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

interface IDBRequest : EventTarget {
    readonly    attribute any                                        result;
    readonly    attribute DOMError                                   error;
    readonly    attribute (IDBObjectStore or IDBIndex or IDBCursor)? source;
    readonly    attribute IDBTransaction                             transaction;
    readonly    attribute IDBRequestReadyState                       readyState;
                attribute EventHandler                               onsuccess;
                attribute EventHandler                               onerror;
};

When a request is made, a new request is returned with its done flag set to false. If a request completes successfully, the done flag is set to true, 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 to true, the error attribute is set to a DOMError type that matches the error, and an event with type error is fired at the request.

The open and deleteDatabase functions on IDBFactory uses a separate interface for its requests in order to make use of the blocked event and upgradeneeded event easier.

interface IDBOpenDBRequest : IDBRequest {
                attribute EventHandler onblocked;
                attribute EventHandler onupgradeneeded;
};

The task source for these tasks is the database access task source.

3.2.2 Event interfaces

This specification fires events with the following custom interfaces:

[Constructor(DOMString type, optional IDBVersionChangeEventInit eventInitDict)]
interface IDBVersionChangeEvent : Event {
    readonly    attribute unsigned long long  oldVersion;
    readonly    attribute unsigned long long? newVersion;
};

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

3.2.3 Opening a database

Window implements IDBEnvironment;

WorkerUtils implements IDBEnvironment;

[NoInterfaceObject]
interface IDBEnvironment {
    readonly    attribute IDBFactory indexedDB;
};

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.

interface IDBFactory {
    IDBOpenDBRequest open (DOMString name, [EnforceRange] optional unsigned long long version);
    IDBOpenDBRequest deleteDatabase (DOMString name);
    short            cmp (any first, any second);
};

3.2.4 Database

A database object can be used to manipulate the objects of that database. It is also the only way to obtain a transaction for that database.

interface IDBDatabase : EventTarget {
    readonly    attribute DOMString          name;
    readonly    attribute unsigned long long version;
    readonly    attribute DOMStringList      objectStoreNames;
    IDBObjectStore createObjectStore (DOMString name, optional IDBObjectStoreParameters optionalParameters);
    void           deleteObjectStore (DOMString name);
    IDBTransaction transaction ((DOMString or sequence<DOMString>) storeNames, optional IDBTransactionMode mode = "readonly");
    void           close ();
                attribute EventHandler       onabort;
                attribute EventHandler       onerror;
                attribute EventHandler       onversionchange;
};

3.2.5 Object Store

interface IDBObjectStore {
    readonly    attribute DOMString      name;
    readonly    attribute any            keyPath;
    readonly    attribute DOMStringList  indexNames;
    readonly    attribute IDBTransaction transaction;
    readonly    attribute boolean        autoIncrement;
    IDBRequest put (any value, optional any key);
    IDBRequest add (any value, optional any key);
    IDBRequest delete (any key);
    IDBRequest get (any key);
    IDBRequest clear ();
    IDBRequest openCursor (optional any range, optional IDBCursorDirection direction = "next");
    IDBIndex   createIndex (DOMString name, (DOMString or sequence<DOMString>) keyPath, optional IDBIndexParameters optionalParameters);
    IDBIndex   index (DOMString name);
    void       deleteIndex (DOMString indexName);
    IDBRequest count (optional any key);
};

3.2.6 Index

Index objects implement the following interface:

interface IDBIndex {
    readonly    attribute DOMString      name;
    readonly    attribute IDBObjectStore objectStore;
    readonly    attribute any            keyPath;
    readonly    attribute boolean        multiEntry;
    readonly    attribute boolean        unique;
    IDBRequest openCursor (optional any range, optional IDBCursorDirection direction = "next");
    IDBRequest openKeyCursor (optional any range, optional IDBCursorDirection direction = "next");
    IDBRequest get (any key);
    IDBRequest getKey (any key);
    IDBRequest count (optional any key);
};

3.2.7 Cursor

Cursor objects implement the following interface:

interface IDBCursor {
    readonly    attribute (IDBObjectStore or IDBIndex) source;
    readonly    attribute IDBCursorDirection           direction;
    readonly    attribute any                          key;
    readonly    attribute any                          primaryKey;
    IDBRequest update (any value);
    void       advance ([EnforceRange] unsigned long count);
    void       continue (optional any key);
    IDBRequest delete ();
};

interface IDBCursorWithValue : IDBCursor {
    readonly    attribute any value;
};

3.2.8 Transaction

Transaction objects implement the following interface:

interface IDBTransaction : EventTarget {
    readonly    attribute IDBTransactionMode mode;
    readonly    attribute IDBDatabase        db;
    readonly    attribute DOMError           error;
    IDBObjectStore objectStore (DOMString name);
    void           abort ();
                attribute EventHandler       onabort;
                attribute EventHandler       oncomplete;
                attribute EventHandler       onerror;
};

3.3.1 Opening a database

The steps for opening a database are defined in the following steps. The algorithm in these steps takes four arguments: the origin which requested the database to be opened, a database name, a database version, and a request.

1. If these steps fail for any reason, return an error with the appropriate type and abort this algorithm.
2. If there is already a database with the given name from the origin origin, then let db be that database.
3. If db was found in previous step, wait until the following conditions are all fulfilled:
   • No already existing connections to db, have non-finished "versionchange" transaction.
   • If db has its delete pending flag set, wait until db has been deleted.
   Note

   If several connections with the same origin and name are waiting due to the above conditions, and those connections have a higher version than the database's current version, then once any of those connections can proceed to the next step in this algorithm it will immediately start a "versionchange" transaction. This prevents the other connections from proceeding until that "versionchange" transaction is finished.

4. If no database with the given name from the origin origin was found, or if it was deleted during the previous step, then create a database with name name, with 0 as version, and with no object stores. Let db be the new database.
5. If version is undefined, then let version be 1 if db was created in the previous step, or the current version of db otherwise.
6. If the version of db is higher than version, abort these steps and return a DOMError of type VersionError.
7. Create a new connection to db and let connection represent it.
8. If the version of db is lower than version, then run the steps for running a "versionchange" transaction using connection, version and request.
9. If the previous step resulted in an error, then return that error and abort these steps. If the "versionchange" transaction in the previous step was aborted, or if connection is closed, return a DOMError of type AbortError and abort these steps. In either of these cases, ensure that connection is closed by running the steps for closing a database connection before these steps are aborted.
10. Return connection.

3.3.2 Transaction Creation steps

When the user agent is to create a transaction it MUST run the following steps. This algorithm takes three arguments: a connection, a mode, and the list storeNames naming the object stores to be included in the scope of the transaction.

1. If storeNames is of type sequence<DOMString> then let scope be the set of unique strings in the sequence. Otherwise, storeNames must be a DOMString; let scope be a set containing one string equal to storeNames. If any of the strings in scope identifies an object store which doesn't exist, throw a DOMException of type NotFoundError. If scope is an empty set throw a DOMException of type InvalidAccessError.
2. If the closePending flag is set on connection then throw a DOMException of type InvalidStateError.
3. Create a transaction using connection as connection, mode as mode, and the object stores identified in scope as scope.
4. Return the created transaction and queue up the remaining steps. When control is returned to the event loop, the implementation MUST set the active flag to false.
5. Wait until the transaction can be started according to the transaction lifetime rules.

3.3.3 Steps for committing a transaction

When taking the steps for committing a transaction the implementation MUST execute the following algorithm. This algorithm takes one argument, the transaction to commit.

1. All the changes made to the database by the transaction are written to the database.
2. If an error occurs while writing the changes to the database, abort the transaction by following the steps for aborting a transaction with the transaction parameter set to transaction and the error parameter set to a value appropriate for the error, for example QuotaExceededError or UnknownError.
3. Queue up an operation to dispatch an event at transaction. The event must use the Event interface and have its type set to "complete". The event does not bubble and is not cancelable. The propagation path for the event is transaction's connection and then transaction.
   Note

   Even if an exception is thrown from one of the event handlers of this event, the transaction is still committed since writing the database changes happens before the event takes places. Only after the transaction has been successfully written is the "complete" event fired.

3.3.4 Steps for aborting a transaction

When taking the steps for aborting a transaction the implementation MUST execute the following algorithm. This algorithm takes two arguments: the transaction to abort, and an error name.

1. All the changes made to the database by the transaction are reverted. For "versionchange" transactions this includes changes to the set of object stores and indexes, as well as the change to the version. Also run the steps for aborting a "versionchange" transaction which reverts changes to all IDBDatabase and IDBObjectStore instances.
2. Unless error was set to null, create a DOMError object and set its name to error. Set transaction's error property to this newly created DOMError.
3. If the transaction's request list contain any requests whose done flag is still false, abort the steps for asynchronously executing a request for each such request and queue a task to perform the following steps:
   1. Set the done flag on the request to true, set result of the request to undefined and set the request's error attribute to a DOMError with a type of AbortError.
   2. Dispatch an event at request. The event must use the Event interface and have its type set to "error". The event bubbles and is cancelable. The propagation path for the event is transaction's connection, then transaction and finally the request. There is no default action for the event.
   Note

   This does not always result in any error events being fired. For example if a transaction is aborted due to an error while committing the transaction, or if it was the last remaining request that failed.

4. Queue up an operation to dispatch an event at transaction. The event must use the Event interface and have its type set to "abort". The event does bubble but is not cancelable. The propagation path for the event is transaction's connection and then transaction.

3.3.5 Steps for asynchronously executing a request

When taking the steps for asynchronously executing a request the implementation MUST run the following algorithm. The algorithm takes a source object and an operation to perform on a database.

These steps can be aborted at any point if the transaction the created request belongs to is aborted using the steps for aborting a transaction

1. Let transaction be the transaction associated with source.
2. If transaction is not active throw a DOMException of type TransactionInactiveError.
3. Create an IDBRequest object and set request to this object. Set request's source to source and add request to the end of the list of requests in transaction. Return this object and queue up the execution of the remaining steps in this algorithm.
   Note

   Cursors override this step to reuse an existing IDBRequest. However they still put the IDBRequest at the end of the list of requests in transaction.

4. Wait until all previously added requests in transaction have their done flag set to true.
5. Perform operation.
6. If performing operation succeeded then set the done flag on the request to true, set result of the request to the result of the request and set the error attribute of the request to undefined. Finally fire a success event at request.
7. If performing operation failed then revert all changes made by operation, set the done flag on the request to true, set result of the request to undefined and set the error attribute on the request to a DOMError with the same error type as the operation that failed. Finally fire an error event at request.
   Note

   This only reverts the changes done by this request, not any other changes made by the transaction.

3.3.6 Steps for extracting a key from a value using a key path

When taking the steps for extracting a key from a value using a key path, the implementation MUST run the following algorithm. The algorithm takes a key path named keyPath and a value named value and in some cases returns a key which may or may not be a valid key.

1. If keyPath is a sequence<DOMString>, then let result be newly constructed empty Array. For each item in the keyPath sequence, perform the following substeps:
   1. Evaluate the steps for extracting a key from a value using a key path using the item from the keyPath sequence as keyPath and value as value.
   2. If the result of the previous step was not a valid key, then abort the overall algorithm and no value is returned.
   3. Add the result of the first sub-step to end of the result array.
   Return result as result of this algorithm and perform no additional steps.
   Note

   This will only ever "recurse" one level since key path sequences can't ever be nested.

2. If keyPath is the empty string, return value and skip the remaining steps.
3. Let remainingKeyPath be keyPath and object be value.
4. If remainingKeyPath has a period in it, assign identifier to be everything before the first period and assign remainingKeyPath to be everything after that first period. Otherwise, assign identifier to be remainingKeyPath and assign remainingKeyPath to be null.
5. If object does not have an property named identifier, then skip the rest of these steps and no value is returned.
6. Assign object to be the value of the property named identifier on object.
7. If remainingKeyPath is not null, go to step 4.
8. Return object.

3.3.7 "versionchange" transaction steps

The steps for running a "versionchange" transaction are as follows. This algorithm takes three arguments: a connection object which is used to update the database, a new version to be set for the database, and a request.

1. Let openDatabases be the set of all IDBDatabase objects, except connection, connected to the same database as connection.

2. Fire a versionchange event at each object in openDatabases that is open. The event MUST NOT be fired on objects which has the closePending flag set. The event MUST use the IDBVersionChangeEvent interface and have the oldVersion property set to db's version and have the newVersion property set to version. This event MUST NOT bubble or be cancelable. The propagation path for the event is just the IDBDatabase object itself.

   Note

   Firing this event might cause one or more of the other objects in openDatabases to be closed, in which case the versionchange event MUST NOT be fired at those objects if that hasn't yet been done.

3. If any of the connections in openDatabases are still not closed, queue up a blocked event for the request. The event MUST use the IDBVersionChangeEvent interface and have the oldVersion property set to db's version and have the newVersion property set to version. This event MUST NOT bubble or be cancelable. The propagation path for the event is just request.

4. Wait until all objects in openDatabases are closed and all of their transactions are finished.
5. Create a new transaction with mode set to "versionchange" and connection used as connection. The scope of the transaction includes every object store in connection. Set its active flag to false. Let transaction represent this transaction.
6. Start transaction. Note that until this transaction is finished, no other connections can be opened to the same database.
7. Let old version be database's version.
8. Set the version of database to version. This change is considered part of the transaction, and so if the transaction is aborted, this change is reverted.
9. Schedule a task to run the following steps:
   1. Set the result property of request to connection.
   2. Set the transaction property of request to transaction.
   3. Fire a upgradeneeded event targeted at request. The event MUST use the IDBVersionChangeEvent interface and have the oldVersion property set to old version and have the newVersion property set to version. The done flag on the request is set to true.
   4. If an exception was propagated out from any event handler while dispatching the event in the previous step, abort the transaction by following the steps for aborting a transaction with the error property set to AbortError.
   5. If for any reason the "versionchange" transaction is aborted the IDBDatabase instance which represents connection will remain unchanged. I.e., its name, version, and objectStoreNames properties will remain the value they were before the transaction was aborted. The default attributes for the IDBDatabase are:

      Attribute	Value
      name	the name provided to IDBFactory.open
      version	0 (zero)
      objectStoresNames	null

10. Execute the transaction.
11. When the transaction is finished, immediately set request's transaction property to null. This MUST be done in the same task as the task firing the complete or abort event, but after those events has been fired.

3.3.8 Steps for aborting a "versionchange" transaction

The steps for aborting a "versionchange" transaction are as follows.

1. IDBDatabase.name is not modified at all. Even if the transaction is used to create a new database, and thus there is no on-disk database, IDBDatabase.name remains as it was.
2. Revert IDBDatabase.version to the version the on-disk database had before the transaction was started. If the "versionchange" transaction was started because the database was newly created, revert IDBDatabase.version to version 0; if the transaction was started in response to a version upgrade, revert to the version it had before the transaction was started. Note that the only time that the IDBDatabase.version property ever changes value is during a "versionchange" transaction.
3. Revert IDBDatabase.objectStoreNames to the list of names that it had before the transaction was started. If the "versionchange" transaction was started because the database was newly created, revert it to an empty list. If the "versionchange" transaction was started in response to a version upgrade, revert to the list of object store names it had before the transaction was started.
4. Revert IDBObjectStore.indexNames (for each object store) to the list of names that IDBObjectStore.indexNames had before the transaction was started. For any object store that was created by the transaction, revert the list to an empty list. For any object store that existed before the transaction was started, revert to the list of index names it had before the transaction was started. For any object store that was deleted during the transaction, revert the list of names to the list it had before the transaction was started, potentially a non-empty list.
   Note

   Although you cannot access object stores by using the IDBTransaction.objectStore function after a transaction is aborted, the page may still have references to object store instances. In that case IDBObjectStore.indexNames can still be accessed.

3.3.9 Database closing steps

The steps for closing a database connection are as follows. These steps take one argument, a connection object.

1. Set the internal closePending flag of connection to true.
2. Wait for all transactions created using connection to complete. Once they are complete, connection is closed.

3.3.10 Database deletion steps

The steps for deleting a database are as follows. The algorithm in these steps takes three arguments: the origin that requested the database to be deleted, a database name, and a request.

1. If there is already a database with the given name from the origin origin, then let db be that database.
2. If no database was found, then these steps are considered successful. Abort these steps.
3. Set db's delete pending flag to true.
4. Let openDatabases be the set of all IDBDatabase objects connected to db.

5. Fire a versionchange event at each object in openDatabases that is open. The event MUST NOT be fired on objects which has the closePending flag set. The event MUST use the IDBVersionChangeEvent interface and have the oldVersion property set to db's version and have the newVersion property set to null. This event MUST NOT bubble or be cancelable.

   Note

   Firing this event might cause one or more of the other objects in openDatabases to be closed, in which case the versionchange event MUST NOT be fired at those objects if that hasn't yet been done.

6. If any of the connections in openDatabases are still not closed, and request was provided, fire a blocked event at request. The event MUST use the IDBVersionChangeEvent interface and have the oldVersion property set to db's version and have the newVersion property set to null. This event MUST NOT bubble or be cancelable.

7. Wait until all objects in openDatabases are closed and all of their transactions are finished.
8. Delete db.

3.3.11 Fire a success event

To fire a success event at a request, the implementation MUST run the following steps:

1. Set transaction to the transaction associated with the source.
2. Set the active flag of transaction to true.
3. Dispatch an event at request. The event must use the Event interface and have its type set to "success". The event does not bubble and is not cancelable. The propagation path for the event is the transaction's connection, then transaction and finally request.
4. Set the active flag of transaction to false.
5. If an exception was propagated out from any event handler while dispatching the event in step 3, abort the transaction by following the steps for aborting a transaction using transaction as transaction parameter, and AbortError as error.

3.3.12 Fire an error event

To fire an error event at a request, the implementation MUST run the following steps:

1. Set transaction to the transaction associated with the source.
2. Set the active flag of transaction to true.
3. Dispatch an event at request. The event must use the Event interface and have its type set to "error". The event bubbles and is cancelable. The propagation path for the event is the transaction's connection, then transaction and finally request. The event's default action is to abort the transaction by running the steps for aborting a transaction using transaction as transaction and the name of request's error property as error. However the default action is not taken if any of the event handlers threw an exception.
4. Set the active flag of transaction to false.
5. If an exception was propagated out from any event handler while dispatching the event in step 3, abort the transaction by following the steps for aborting a transaction using transaction as transaction parameter, and AbortError as error. This is done even if the error event is not canceled.
   Note

   This means that if an error event is fired and any of the event handlers throw an exception, the error property on the transaction is set to an AbortError rather than whatever DOMError the error property on the request was set to. Even if preventDefault is never called.

3.3.13 Steps to assign a key to a value using a key path

The steps to assign a key to a value using a key path are as follows:

1. Let remainingKeyPath be keyPath and object be value.
2. If object is not an Object object or an Array object (see structured clone algorithm [HTML5]), then throw a DOMException of type DataError.
3. If remainingKeyPath has a period in it, assign identifier to be everything before the first period, and assign remainingKeyPath to be everything after that first period. Otherwise, go to step 7.
4. If object does not have a property named identifier, then set a property named identifier on object with the value of a new Object.
5. Assign object to be the value of the property named identifier on object.
6. Go to step 2.
7. Note

   The steps leading here ensure that remainingKeyPath is a single identifier name (that is, a string without periods) by this step. The steps also ensure that object is an Object or an Array, and not a Date, RegExp, Blob, or other nonsupported type.

8. Let identifier be remainingKeyPath.
9. Set a property named identifier on object with the value key.

3.4.1 Object Store Storage Operation

The steps for storing a record into an object store are as follows. The algorithm run by these steps takes four arguments: an object store store, a value, an optional key, and a no-overwrite flag.

1. If store does use in-line keys and evaluting store's key path on value does yield a value, then set key to that result.
2. If store uses a key generator and key is undefined, set key to the next generated key. If store also uses in-line keys, then set the property in value pointed to by store's key path to the new value for key, as shown in the steps to assign a key to a value using a key path. If the current number of a key generator reaches above the value 2^53 (9007199254740992) any attempt to use the key generator to generate a new key fails with a ConstraintError.
3. If store uses a key generator, this key generator was not used to generate a value for key in the previous step, key is defined to a Number and this number is larger than, or equal to, the next key that store's key generator would generate, change store's key generator such that the next key it generates is the lowest integer larger than key.
4. If the no-overwrite flag was passed to these steps and is set, and a record already exists in store with its key equal to key, then this operation failed with a ConstraintError. Abort this algorithm without taking any further steps.
5. If a record already exists in store with its key equal to key, then remove the record from store using the steps for deleting records from an object store.
6. Store a record in store containing key as its key and object as its value. The record is stored in the object store's list such that the list is sorted according key of the records in ascending order.
7. If there are any indexes which reference store, perform the following sub steps on each such index.
   1. Set index to the index.
   2. Evaluate index's key path on value. If this does not yield a value, take no further actions for this index. Otherwise set the result to index key.
   3. If index's multiEntry flag is false or if index key is not an Array, and if index key is not a valid key, take no further actions for this index.
   4. If index's multiEntry flag is true, and index key is an Array, remove any elements from index key that are not valid keys and remove any duplicate elements from index key such that only one instance of the duplicate value remains.
      Note

      For example, the following value of index key [10, 20, null, 30, 20] is converted to [10, 20, 30].

      Note

      After this step index key is or contains only valid keys.

   5. If index's multiEntry flag is false, or if index key is not an Array, and if index already contains a record with key equal to index key, and index has its unique flag set to true, then this operation failed with a ConstraintError. Abort this algorithm without taking any further steps.
   6. If index's multiEntry flag is true and index key is an Array, and if index already contains a record with key equal to any of the values in index key, and index has its unique flag set to true, then this operation failed with a ConstraintError. Abort this algorithm without taking any further steps.
   7. If index's multiEntry flag is false, or if index key is not an Array, then store a record in index containig index key as its key and key as its value. The record is stored in index's list of records such that the list is sorted primarily on the records keys, and secondarily on the records values, in ascending order.
   8. If index's multiEntry flag is true and index key is an Array, then for each item in index key store a record in index containig the items value as its key and key as its value. The records are stored in index's list of records such that the list is sorted primarily on the records keys, and secondarily on the records values, in ascending order.
      Note

      Note that it is legal for the Array to have length 0, in this case no records are added to the index.

      Note

      If any of the items in the Array are themselves an Array, then the inner Array is used as a key for that entry. In other words, Arrays are not recursively "unpacked" to produce multiple rows. Only the outer-most Array is.

8. The result of this algorithm is key.

3.4.2 Object Store Retrieval Operation

The steps for retrieving a value from an object store are as follows. These steps MUST be run with two parameters - the record key and the object store.

1. Let key be the key and store be the object store passed to these steps.
2. If key is not a key range then retreive the record with key key from store. If key is a key range, then retreive the first record from store whose key is in key.
3. If no record was found, the result of this algorithm is undefined.
4. The result of this algorithm is a new structured clone of the value in the found record.

3.4.3 Index Referenced Value Retrieval Operation

The steps for retrieving a referenced value from an index are as follows. These steps MUST be run with two parameters - the record key and the index.

1. Let key be the key and index be the index passed to these steps.
2. If key is not a key range then find the first record with key key from index. If key is a key range, then find the first record from index whose key is in key.
3. If no record was found, the result of this algorithm is undefined.
4. Otherwise, the result of the operation is a structured clone of the referenced value of the found record.

3.4.4 Index Value Retrieval Operation

The steps for retrieving a value from an index are as follows. These steps MUST be run with two parameters - the record key and the index.

1. Let key be the key and index be the index passed to these steps.
2. If key is not a key range then find the first record with key key from index. If key is a key range, then find the first record from index whose key is in key.
3. If no record was found, the result of this algorithm is undefined.
4. If a record was found, the result of this algorithm is the value of the found record.

3.4.5 Object Store Deletion Operation

The steps for deleting records from an object store are as follows. The algorithm run by these steps takes two parameters: an object store store and a key.

1. If the key parameter is a key range then let range be that key range. Otherwise, let range be a key range which containing only key.
2. Remove all records, if any, from store with key in range.
3. In all indexes which reference store, remove all records whose value is in range, if any such records exist.
4. The result of this algorithm is undefined.

3.4.6 Object Store Clear Operation

The steps for clearing an object store are as follows. The algorithm run by these steps takes one parameter: an object store store.

1. Remove all records from store.
2. In all indexes which reference store, remove all records.
3. The result of this algorithm is undefined.

3.4.7 Cursor Iteration Operation

The steps for iterating a cursor are as follows. The algorithm run by these steps takes two parameters: a cursor and optional key to iterate to.

1. Let source be cursor's source, let records be list of records in source, let direction be cursor's direction, let position be cursor's position, let object store position be cursor's object store position and let range be cursor's range.
   Note

   source is always an object store or an index.

   Note

   records is always sorted in ascending key order. In the case of source being an index, records is secondarily sorted in ascending value order (where the value in an index is the key of the record in the referenced object store).

2. If direction is "next", let found record be the first record in records which satisfy all of the following requirements:

   • If key is defined, the record's key is greater than or equal to key.
   • If position is defined, and source is an object store, the record's key is greater than position.
   • If position is defined, and source is an index, the record's key is equal to position and the record's value is greater than object store position or the record's key is greater than position.
   • If range is defined, the record's key is in range.

   If direction is "nextunique", let found record be the first record in records which satisfy all of the following requirements:

   • If key is defined, the record's key is greater than or equal to key.
   • If position is defined, the record's key is greater than position.
   • If range is defined, the record's key is in range.

   If direction is "prev", let found record be the last record in records which satisfy all of the following requirements:

   • If key is defined, the record's key is less than or equal to key.
   • If position is defined, and source is an object store, the record's key is less than position.
   • If position is defined, and source is an index, the record's key is equal to position and the record's value is less than object store position or the record's key is less than position.
   • If range is defined, the record's key is in range.

   If direction is "prevunique", let temp record be the last record in records which satisfy all of the following requirements:

   • If key is defined, the record's key is less than or equal to key.
   • If position is defined, the record's key is less than position.
   • If range is defined, the record's key is in range.

   If temp record is defined, let found record be the first record in records whose key is equal to temp record's key.

3. If found record is not defined, set cursor's key to undefined. If source is an index, set cursor's object store position to undefined. If cursor implements IDBCursorWithValue then set cursor's value to undefined. The result of this algorithm is null. Abort these steps.

4. Set cursor's position to found record's key. If source is an index, set cursor's object store position to found record's value.

5. Set cursor's key to found record's key.

   If cursor implements IDBCursorWithValue then set cursor's value to a structured clone of found record referenced value.

6. Set cursor's got value flag to true.
   Note

   Once data has been successfully read, schedule a task which when run will set the cursor's value and fire a success event.

7. The result of the algorithm is cursor.