Indexed Database API

3.1.1 Keys

In order to efficiently retrieve records stored in an indexed database, a user agent needs to organize each record by its key. Conforming user agents must support the use of values of IDL data types DOMString and long as well as the value null as keys.

For purposes of comparison, a DOMString key is always evaluated higher than any long key. Moreover, null always evaluates lower than any DOMString or long key.

3.1.2 Values

Values can be any data type supported by the structured clone algorithm [HTML5]. This includes simple types such as DOMString and Date as well as Object and Array instances.

A database may choose to derive a key from the contents of the value being stored. In such a case, only Object instances may be stored as values. Only the direct enumerable properties of a stored Object instance can be used to derive a key value.

3.1.3 Object Store

An object store is a persistent storage that holds key-value pairs, also called records. An object store's records are sorted by keys so as to enable fast insertion and look up as well as ordered retrieval. Every object store has a name.

An object store must have a unique key generator, if it uses keys generated from a monotonically increasing sequence. Alternatively, if an application provides keys, they can either be identified as a part of the value being stored, also called in-line keys, or be identified separately, also called out-of-line keys. No two records in an object store may be identified by the same key. An object store must have a key path if it uses in-line keys. The key path must be the name of an enumerated property of all objects being stored in that object store.

Concurrent access to an object store may be isolated in one of three modes. Any number of readers may concurrently access an object store. A writer is not allowed if there is any reader concurrently accesing the object store, unless the reader is detached, i.e., looking at a snapshot view of the data that does not change once created.

The ObjectStore interface is used to access the metadata of an object store.

interface ObjectStore {
    const unsigned short READ_WRITE = 0;
    const unsigned short READ_ONLY = 1;
    const unsigned short SNAPSHOT_READ = 2;
    readonly attribute unsigned short mode;
    readonly attribute DOMString      name;
    readonly attribute DOMString      keyPath;
    readonly attribute DOMStringList  indexNames;
};

3.1.4 Index

Records in an object store can be retrieved by means of the record's key. However, that may not be always adequate to recall records. An index is used to lookup records in an object store other than through a record key.

An index is a specialized persistent store that holds key-value pairs such that each value is the key of objects in the referenced object store. An index may allow duplicate values for a key, unlike an object store, only if its unique flag is not set. Every index has a name.

If an index is auto-populated, then the user agent populates records using the values stored in the referenced object store. An auto-populated index must have a key path, which must be the name of an enumerated property of all objects being stored in the referenced object store. The auto-populated index record corresponding to an object store record must satisfy the following index maintenance conditions:

• index record key = value of the enumerated property at the key path in the object store record value
• index record value = object store record key

The Index interface is used to access the metadata of an index.

interface Index {
    readonly attribute DOMString name;
    readonly attribute DOMString storeName;
    readonly attribute DOMString keyPath;
    readonly attribute boolean   unique;
};

3.1.5 Database

Each origin has an associated set of databases. A database comprises:

• one or more object stores and
• any number of indexes.

The object stores and indexes of a database are also referred as its objects.

Each database has a valid name and a human readable description A valid name is any string including the empty string. Names must be compared in a case-sensitive manner.

Each database also has a current version.

The object store name and index name must be valid and unique within the database.

When a database is opened, that creates a connection. There may be multiple connections to a given database at any given time. A connection that is attempting to read a given piece of data in a database is called a reader and one that is attempting to write that piece of data is called a writer. There may be zero or one active transaction in a connection.

A Database object represents a connection to a database. There is no way to enumerate the databases available for an origin from this API.

interface Database {
    readonly attribute DOMString     name;
    readonly attribute DOMString     description;
    readonly attribute DOMString     version;
    readonly attribute DOMStringList objectStores;
    readonly attribute DOMStringList indexes;
    readonly attribute Transaction   currentTransaction;
};

3.1.6 Key Range

An individual record can be retrieved from an object store using either the record's key or the key applicable for some index that references that object store. Multiple records can be fetched using a key range. A key range is a continuous interval over some data type used for keys.

A key range may be left-bounded or right-bounded if 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 left- and right-bounded and unbounded otherwise. A valid key range must be either half-bounded or bounded. A key range may be open, i.e., not including its endpoints or closed, i.e., including its endpoints. A key range may consist of a single value.

The KeyRange interface is used to define a key range.

interface KeyRange {
    const unsigned short SINGLE = 0;
    const unsigned short LEFT_OPEN = 1;
    const unsigned short RIGHT_OPEN = 2;
    const unsigned short LEFT_BOUND = 4;
    const unsigned short RIGHT_BOUND = 8;
    readonly attribute any            left;
    readonly attribute any            right;
    readonly attribute unsigned short flags;
    KeyRange only (in any value);
    KeyRange leftBound (in any bound, in optional boolean open);
    KeyRange rightBound (in any bound, in optional boolean open);
    KeyRange bound (in any left, in any right, in optional boolean openLeft, in optional boolean openRight);
};

3.1.7 Cursor

Cursors are a transient mechanism used to iterate over multiple records in a database. The 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. A cursor maintains a position over this series, which moves in a direction that is either monotonically increasing or decreasing order of the record keys.

interface Cursor {
    const unsigned short NEXT = 0;
    const unsigned short NEXT_NO_DUPLICATE = 1;
    const unsigned short PREV = 2;
    const unsigned short PREV_NO_DUPLICATE = 3;
    readonly attribute unsigned short direction;
};

3.1.8 Transaction

A transaction has a scope and a database. A transaction's scope is either static or dynamic. If the scope is static, it can cover either all the object stores and indexes in a database or it may include a subset of them.

A connection may have at most one transaction at any given time. Moreover, there may not be any overlap among the scopes of all open connections to a given database.

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

Transactions are expected to be short lived. Conforming user agents may terminate transactions that take too long to complete in order to free up storage resources that are locked by a long running transaction.

interface Transaction {
    attribute boolean  static;
    attribute Database db;
};

3.2.1 Opening the database

The steps for opening a database are as follows. These steps must be run with an origin, a database name and description. All the steps must be run atomically:

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 with the given name from the origin origin exists, then create the database db with the name and description passed to these steps.
3. Create a connection to db and call it result.
4. Return result.

3.2.2 Object Store Storage steps

The steps for storing a record into an object store are as follows. These steps must be run with four parameters: the object store, a value, an optional key, and an optional no-overwrite flag.

1. Let store be the object store, key be the key and value be the value passed to these steps.
2. If store uses out-of-line keys but no key generator, then a key must be passed to these steps. If not, terminate these steps and set error code DATA_ERR.
3. If store uses in-line keys, then let key be the property of object at store's key path.
4. If key is defined and not null, then skip the next step.
5. Produce a structured clone of value and call it object.
6. Perform the following steps.
   1. Using store's key generator, produce the next key and store it as key.
   2. If store uses in-line keys, then store key as the property value for object at store's key path.
7. If the no-overwrite flag was passed to these steps and is set, and a record already exists with its key being key, then terminate these steps and set error code CONSTRAINT_ERR.

8. Store a record in store containing key as its key and object as its value. If any indexes are auto-populated for store, then store a record in that index according to index maintenance conditions.

   Storing would mean inserting if no record exists for that key or updating an existing record, otherwise. Auto populated index record will also be respectively inserted or updated depending on what storing results in.
9. Return the key.

3.2.3 Index Storage steps

The steps for storing a record into an index are as follows. These steps must be run with four parameters: the index, a key, a value, and a no-overwrite flag.

1. Let index be the index, key be the key and value be the value passed to these steps.
2. If index has a key path, then terminate these steps and set error code CONSTRAINT_ERR.
3. If the no-overwrite flag was passed to these steps and is set, and a record already exists in index with its key being key, then terminate these steps and set error code CONSTRAINT_ERR.
4. If no record exists in index's referenced object store whose key is value, then terminate these steps and set error code CONSTRAINT_ERR.

5. Store a record in index containing key as its key and value as its value.

   Storing would mean inserting if no record exists for that key or updating an existing record, otherwise.
6. Return the key.

3.2.4 Object Store Retrieval steps

The steps for retrieving a record 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 no record exists with key key in store, then terminate these steps and set error code NOT_FOUND_ERR.
3. Return the a new structured clone of the value in the record with key key in store.

3.2.5 Index Referenced Value Retrieval steps

The steps for retrieving a record 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 no record exists with key key in index, then terminate these steps and set error code NOT_FOUND_ERR.
3. Let value be the value of the record with key key in index.
4. Return the value for the record with key value in index's referenced object store.

3.2.6 Index Value Retrieval steps

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 no record exists with key key in index, then terminate these steps and set error code NOT_FOUND_ERR.
3. Return the value of the record with key key in index.

3.2.7 Obejct Store Deletion steps

The steps for deleting a record from an object store are as follows. These steps must be run with two parameters: the key of the record to be deleted and the object store.

1. Let key be the key and store be the object store passed to these steps.
2. If no record exists with key key in store, then terminate these steps and set error code NOT_FOUND_ERR.
3. If any indexes are auto-populated for store, then remove the record in that index according to index maintenance conditions.
4. Remove the record from store with key key.

3.2.8 Index Deletion steps

The steps for deleting a record from an index are as follows. These steps must be run with two parameters: the key of the record to be deleted and the index.

1. Let key be the key and index be the index passed to these steps.
2. If no record exists with key key in index, then terminate these steps and set error code NOT_FOUND_ERR.
3. Remove the records from index with key key.

3.2.9 Transaction Creation steps

When the user agent is to create a transaction it must run the following steps. These steps must be run with two parameters - database and an optional list of names of database objects to be reserved.

1. If the database passed to these steps has an active transaction, then terminate these steps and set error code NON_TRANSIENT_ERR.
2. Pick the appropriate steps:

   If these steps are not called with a list of database objects

   Acquire a lock on the entire database.

   If these steps are called with a non-empty list of database objects

   1. If any of the objects in this array is not a database object, then set code to NON_TRANSIENT_ERR and jump to the last step.
   2. Acquire appropriate locks on each of the database objects and the objects they depend on in an ordered sequence.
      If the database does not allow fine grained locking, then a user agent may obtain a shared or exclusive lock on the database.

   If these steps are called with an empty array of database objects

   Do not acquire locks on any database objects now. Locks are obtained as the application attempts to access those objects.

   Using the database in this style may lead to deadlocks. Programmers must use caution to acquire and release database objects in the same global order to avoid deadlocks.

3. If a timeout duration is passed to these steps and is exceeded when acquiring locks, then set code to TIMEOUT_ERR and jump to the last step.
4. Open a new transaction to the database, and create a Transaction object that represents that transaction. Let transaction be this object.
5. Set the current transaction of this Database object to transaction.
6. Return transaction. End these steps.
7. This step is only performed in case of error. If this step is performed synchronously, then raise a newly constructed DatabaseException exception exception with the code code.

3.3.1 Opening a database connection

Worker objects must implement the EnvironmentSync interface.

WorkerUtils implements EnvironmentSync;

interface EnvironmentSync {
    readonly attribute IndexedDatabase indexedDB;
};

interface IndexedDatabase {
    DatabaseSync open (in DOMString name, in DOMString description, in optional boolean modifyDatabase) raises (DatabaseException);
};

3.3.2 Database connection

A database connection can be used to manipulate the objects of that database. That is also the only means of obtaining a transaction for that database.

interface DatabaseSync : Database {
    ObjectStoreSync createObjectStore ([Null=Empty] in DOMString name, [Null=Null] in DOMString keyPath, in optional boolean autoIncrement) raises (DatabaseException);
    ObjectStoreSync openObjectStore (in DOMString name, in optional unsigned short mode) raises (DatabaseException);
    IndexSync       createIndex ([Null=Empty] in DOMString name, [Null=Empty] in DOMString storeName, in DOMString keyPath, in optional boolean unique) raises (DatabaseException);
    IndexSync       openIndex (in DOMString name) raises (DatabaseException);
    void            removeObjectStore (in DOMString storeName) raises (DatabaseException);
    void            removeIndex (in DOMString indexName) raises (DatabaseException);
    void            setVersion ([Null=Null] in DOMString version);
    TransactionSync transaction (in optional DOMStringList storeNames, in optional unsigned int timeout) raises (DatabaseException);
};

3.3.3 Object Store

var db = indexedDB.open('AddressBook', 'Address Book');
if (db.version !== '1') {
   var olddb = indexedDB.open('AddressBook', 'Address Book');
   olddb.createObjectStore('Contact', 'id', true);
   olddb.setVersion('1');
}

var store = db.openObjectStore('Contact');

var lincoln = {name: 'Lincoln', number: '7012'};
var contact = store.put(lincoln);
// contact.id === 1

var contact = store.<>get(1);
// contact.name === 'Lincoln'

var abraham = {id: 1, name: 'Abraham', number: '2107'};
store.put(abraham);

var contact = store.get(1);
// contact.id === 1 && contact.name === 'Abraham';

var range = new KeyRange.bound(2, 4);
var cursor = store.openCursor(range);
// each value is a contact and each key is the id for that  
// contact whose id is between 2 and 4, both inclusive
cursor.continue();

interface ObjectStoreSync : ObjectStore {
    any        put (in any value, in optional any key, in optional boolean noOverwrite) raises (DatabaseException);
    void       delete (in any key) raises (DatabaseException);
    any        get (in any key) raises (DatabaseException);
    CursorSync openCursor (in optional KeyRange range, in optional unsigned short direction) raises (DatabaseException);
};

3.3.4 Index

var db = indexedDB.open('AddressBook', 'Address Book');
if (db.version === '1') {
   var olddb = indexedDB.open('AddressBook', 'Address Book');
   olddb.createObjectStore('Contact', 'id', true);
   olddb.createIndex('ContactName', 'Contact', 'name', false);
   olddb.setVersion('2');
}

var index = db.openIndex('ContactName');
var id = index.get('Lincoln');
// id === 1

var range = new KeyRange.bound('L', 'M');
var cursor = index.openCursor(range);
// each value is a contact and each key is the name for that  
// contact whose name's first letter is either L or M
cursor.continue();

var range = new KeyRange.bound('L', 'M');
var cursor = index.openObjectCursor(range);
// each value is a contact and each key is the name for that  
// contact whose name's first letter is either L or M
cursor.continue();

interface IndexSync {
    void openObjectCursor (in optional KeyRange range, in optional unsigned short direction) raises (DatabaseException);
    void openCursor (in optional KeyRange range, in optional unsigned short direction) raises (DatabaseException);
    any  put (in any value, in optional any key, in optional boolean noOverwrite) raises (DatabaseException);
    any  getObject (in any key) raises (DatabaseException);
    any  get (in any key) raises (DatabaseException);
    void delete (in any key) raises (DatabaseException);
};

3.3.5 Cursor

Using the synchronous API, an application can process all the records in the cursor's range. No two values provided by the user agent to callbacks processing data in this cursor can be identical.

var objects = ...
var cursor = objects.openCursor();
// act on each object and continue the cursor to its end
cursor.continue();

var objects = ...
var count = objects.openCursor(Cursor.PREV);
// act on each object and continue the cursor to its end
cursor.continue();

var objects = ...
var range = KeyRange.leftBound(key);
objects.openCursor(range, Cursor.NEXT_NO_DUPLICATE);
// act on each object and continue the cursor to its end
cursor.continue();

var objects = ...
var range = KeyRange.bound(start, end);
objects.openCursor(range);
// act on each object and continue the cursor to its end
cursor.continue();

interface CursorSync {
    readonly attribute any                key;
             attribute any                value setraises (DatabaseException);
    readonly attribute unsigned long long count;
    bool continue (in optional any key);
    void delete () raises (DatabaseException);
};

3.3.6 Transaction

When an application creates a transaction synchronously, it blocks until the user agent is able to reserve the required database objects.

interface TransactionSync : Transaction {
    void abort () raises (DatabaseException);
    void commit () raises (DatabaseException);
};

Once a transaction is aborted or committed, the active transaction on this database connection is removed. A new transaction can be created to perform operations atomically.

3.3.7 The DatabaseException Interface

exception DatabaseException {
    const unsigned short UNKNOWN_ERR = 0;
    const unsigned short NON_TRANSIENT_ERR = 1;
    const unsigned short NOT_FOUND_ERR = 2;
    const unsigned short CONSTRAINT_ERR = 3;
    const unsigned short DATA_ERR = 4;
    const unsigned short NOT_ALLOWED_ERR = 5;
    const unsigned short SERIAL_ERR = 11;
    const unsigned short RECOVERABLE_ERR = 21;
    const unsigned shrot TRANSIENT_ERR = 31;
    const unsigned short TIMEOUT_ERR = 32;
    const unsigned short DEADLOCK_ERR = 33;
    attribute unsigned short code;
    attribute DOMString      message;
};

3.4.2 The DBRequest Interface

The DBRequest interface provides means to access results of asynchronous requests to databases and database objects using event handler attributes [DOM-LEVEL-3-EVENTS].

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

interface DBRequest {
    void abort ();
    const unsigned short INITIAL = 0;
    const unsigned short LOADING = 1;
    const unsigned short DONE = 2;
    readonly attribute unsigned short readyState;
    readonly attribute DatabaseError  error;
    readonly attribute any            result;
             attribute Function       onsuccess;
             attribute Function       onerror;
};

DBRequest implements EventTarget;

When a request is made, the readyState changes to LOADING. Once the result of the request is available, the readyState changes to DONE, place the result of the request in result, and aueue a task to fire an event with the name success, with no namespace, which does not bubble, is not cancelable, and which uses the Event interface at each Window object.

If an exception occurs while performing the operation, the readyState changes to DONE, the error information is placed in a new DatabaseError object at the error attribute, and queue a task to fire an event with the name error, with no namespace, which does not bubble, is not cancelable, and which uses the Event interface at each Window object.

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

3.4.3 Asynchronous Request API

Window objects must implement the Environment interface.

Window implements Environment;

interface Environment {
    readonly attribute IndexedDatabaseRequest indexedDB;
};

Every interface for making asynchronous requests includes a DBRequest object that communicates back to the requesting application through events. This design means that only a single request can be active on any database or object handle at a time. If a second request is started, the user agent must abort any previous active request.

interface IndexedDatabaseRequest {
    readonly attribute DBRequest request;
    void open (in DOMString name, in DOMString description, in optional boolean modifyDatabase) raises (DatabaseException);
};

interface DatabaseRequest : Database {
    readonly attribute DBRequest request;
    void createObjectStore ([Null=Empty] in DOMString name, [Null=Null] in DOMString keyPath, in optional boolean autoIncrement);
    void openObjectStore (in DOMString name, in optional unsigned short mode);
    void createIndex ([Null=Empty] in DOMString name, [Null=Empty] in DOMString storeName, in DOMString keyPath, in optional boolean unique);
    void openIndex (in DOMString name);
    void removeObjectStore (in DOMString storeName);
    void removeIndex (in DOMString indexName);
    void setVersion ([Null=Null] in DOMString version);
    void transaction (in optional DOMStringList storeNames, in optional unsigned int timeout);
};

interface ObjectStoreRequest : ObjectStore {
    readonly attribute DBRequest request;
    void put (in any value, in optional any key, in optional boolean noOverwrite);
    void delete (in any key);
    void get (in any key);
    void openCursor (in optional KeyRange range, in optional unsigned short direction);
};

interface IndexRequest : Index {
    readonly attribute DBRequest request;
    void openObjectCursor (in optional KeyRange range, in optional unsigned short direction);
    void openCursor (in optional KeyRange range, in optional unsigned short direction);
    void put (in any value, in optional any key, in optional boolean noOverwrite);
    void getObject (in any key);
    void get (in any key);
    void delete (in any key);
};

interface CursorRequest : Cursor {
    readonly attribute DBRequest          request;
    readonly attribute any                key;
    readonly attribute any                value;
    readonly attribute unsigned long long count;
    void update (in any value);
    void continue (in optional any key);
    void delete ();
};

interface TransactionRequest : Transaction {
    readonly attribute DBRequest request;
    void abort ();
    void commit ();
};

3.4.4 Events

The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by objects implementing the DBRequest interface:

3.4.5 The DatabaseError Interface

Errors in the asynchronous database API are reported using callbacks that have a DatabaseError object as one of their arguments.

interface DatabaseError {
    attribute unsigned short code;
    attribute DOMString      message;
};