Indexed Database API

2.1 Dependencies

This specification relies on several other underlying specifications.

HTML5

The terms and algorithms document base URL, event handler attributes, event handler event type, Function, origin, same origin, structured clone, structured clone algorithm, task, task source, and queue a task are defined by the HTML 5 specification [HTML5].

WebWorkers

The term Worker is defined by the WebWorkers specification [WEBWORKERS].

3.1 Constructs

An indexed database is made of records holding simple values and hierarchical objects. Each record consists of a key and a value.

interface IDBKeyRange {
    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;
    IDBKeyRange only (in any value);
    IDBKeyRange leftBound (in any bound, in optional boolean open);
    IDBKeyRange rightBound (in any bound, in optional boolean open);
    IDBKeyRange bound (in any left, in any right, in optional boolean openLeft, in optional boolean openRight);
};

exception IDBDatabaseException {
    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 short TRANSIENT_ERR = 31;
    const unsigned short TIMEOUT_ERR = 32;
    const unsigned short DEADLOCK_ERR = 33;
    attribute unsigned short code;
    attribute DOMString      message;
};

3.2 Asynchronous APIs

The asynchronous API methods return without blocking the calling thread. All asynchronous operations return an IDBRequest instance, which can be used to access the results of the operation as they become available.

[NoInterfaceObject]
interface IDBEvent : Event {
    readonly attribute any source;
};

[NoInterfaceObject]
interface IDBSuccessEvent : IDBEvent {
    readonly attribute any result;
};

[NoInterfaceObject]
interface IDBTransactionEvent : IDBSuccessEvent {
    readonly attribute IDBTransaction transaction;
};

[NoInterfaceObject]
interface IDBErrorEvent : IDBEvent {
    readonly attribute unsigned short code;
    readonly attribute DOMString      message;
};

[NoInterfaceObject]
interface IDBVersionChangeEvent : IDBEvent {
    readonly attribute DOMString version;
};

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

[NoInterfaceObject]
interface IDBRequest : EventTarget {
    void abort ();
    const unsigned short LOADING = 1;
    const unsigned short DONE = 2;
    readonly attribute unsigned short readyState;
             attribute Function       onsuccess;
             attribute Function       onerror;
};

Window implements IDBEnvironment;

Worker implements IDBEnvironment;

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

[NoInterfaceObject]
interface IDBFactory {
    readonly attribute DOMStringList databases;
    IDBRequest open (in DOMString name, in DOMString description) raises (IDBDatabaseException);
};

[NoInterfaceObject]
interface IDBDatabase {
    readonly attribute DOMString     name;
    readonly attribute DOMString     description;
    readonly attribute DOMString     version;
    readonly attribute DOMStringList objectStores;
    IDBObjectStore createObjectStore (in DOMString name, [TreatNullAs=EmptyString] in optional DOMString keyPath, in optional boolean autoIncrement) raises (IDBDatabaseException);
    IDBObjectStore objectStore (in DOMString name, in optional unsigned short mode, in optional unsigned long timeout) raises (IDBDatabaseException);
    void           removeObjectStore (in DOMString name) raises (IDBDatabaseException);
    IDBRequest     setVersion ([TreatNullAs=EmptyString] in DOMString version);
    IDBTransaction transaction (in optional DOMStringList storeNames, in optional unsigned short mode, in optional unsigned long timeout) raises (IDBDatabaseException);
    void           close ();
};

[NoInterfaceObject]
interface IDBObjectStore {
    readonly attribute DOMString     name;
    readonly attribute DOMString     keyPath;
    readonly attribute DOMStringList indexNames;
    IDBRequest put (in any value, in optional any key) raises (IDBDatabaseException);
    IDBRequest add (in any value, in optional any key) raises (IDBDatabaseException);
    IDBRequest remove (in any key) raises (IDBDatabaseException);
    IDBRequest get (in any key) raises (IDBDatabaseException);
    IDBRequest openCursor (in optional IDBKeyRange range, in optional unsigned short direction) raises (IDBDatabaseException);
    IDBIndex   createIndex (in DOMString name, in DOMString keyPath, in optional boolean unique) raises (IDBDatabaseException);
    IDBIndex   index (in DOMString name) raises (IDBDatabaseException);
    void       removeIndex (in DOMString indexName) raises (IDBDatabaseException);
};

[NoInterfaceObject]
interface IDBIndex {
    readonly attribute DOMString name;
    readonly attribute DOMString storeName;
    readonly attribute DOMString keyPath;
    readonly attribute boolean   unique;
    IDBCursor  openObjectCursor (in optional IDBKeyRange range, in optional unsigned short direction) raises (IDBDatabaseException);
    IDBRequest openCursor (in optional IDBKeyRange range, in optional unsigned short direction) raises (IDBDatabaseException);
    IDBRequest getObject (in any key) raises (IDBDatabaseException);
    IDBRequest get (in any key) raises (IDBDatabaseException);
};

[NoInterfaceObject]
interface IDBCursor {
    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;
    readonly attribute any                key;
    readonly attribute any                value;
    readonly attribute unsigned long long count;
    IDBRequest update (in any value) raises (IDBDatabaseException);
    boolean    continue (in optional any key);
    IDBRequest remove () raises (IDBDatabaseException);
};

[NoInterfaceObject]
interface IDBTransaction : EventTarget {
    const unsigned short READ_WRITE = 0;
    const unsigned short READ_ONLY = 1;
    const unsigned short SNAPSHOT_READ = 2;
    const unsigned short VERSION_CHANGE = 3;
    readonly attribute unsigned short mode;
    readonly attribute IDBDatabase    db;
    IDBObjectStore objectStore (in DOMString name) raises (IDBDatabaseException);
    void           abort ();
             attribute Function       onabort;
             attribute Function       oncomplete;
             attribute Function       ontimeout;
};

[NoInterfaceObject]
interface IDBDynamicTransaction : EventTarget {
    readonly attribute IDBDatabase db;
    IDBRequest openObjectStore (in DOMString name, in optional unsigned short mode);
    void       abort ();
             attribute Function    onabort;
             attribute Function    oncomplete;
             attribute Function    ontimeout;
};

3.3 Synchronous APIs

WorkerUtils implements IDBEnvironmentSync;

[NoInterfaceObject]
interface IDBEnvironmentSync {
    readonly attribute IDBFactorySync indexedDBSync;
};

[NoInterfaceObject]
interface IDBFactorySync {
    IDBDatabaseSync open (in DOMString name, in DOMString description) raises (IDBDatabaseException);
};

[NoInterfaceObject]
interface IDBDatabaseSync {
    readonly attribute DOMString     name;
    readonly attribute DOMString     description;
    readonly attribute DOMString     version;
    readonly attribute DOMStringList objectStores;
    IDBObjectStoreSync createObjectStore (in DOMString name, [Null=Null] in DOMString keyPath, in optional boolean autoIncrement) raises (IDBDatabaseException);
    IDBObjectStoreSync openObjectStore (in DOMString name, in optional unsigned short mode) raises (IDBDatabaseException);
    void               removeObjectStore (in DOMString storeName) raises (IDBDatabaseException);
    void               setVersion ([TreatNullAs=EmptyString] in DOMString version);
    IDBTransactionSync transaction (in optional DOMStringList storeNames, in optional unsigned long timeout) raises (IDBDatabaseException);
};

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 IDBKeyRange.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();

[NoInterfaceObject]
interface IDBObjectStoreSync {
    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;
    any           put (in any value, in optional any key) raises (IDBDatabaseException);
    any           add (in any value, in optional any key) raises (IDBDatabaseException);
    void          remove (in any key) raises (IDBDatabaseException);
    any           get (in any key) raises (IDBDatabaseException);
    IDBIndexSync  createIndex (in DOMString name, in DOMString keyPath, in optional boolean unique);
    IDBIndexSync  openIndex (in DOMString name) raises (IDBDatabaseException);
    void          removeIndex (in DOMString indexName) raises (IDBDatabaseException);
    IDBCursorSync openCursor (in optional IDBKeyRange range, in optional unsigned short direction) raises (IDBDatabaseException);
};

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 IDBKeyRange.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 IDBKeyRange.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();

[NoInterfaceObject]
interface IDBIndexSync {
    readonly attribute DOMString name;
    readonly attribute DOMString storeName;
    readonly attribute DOMString keyPath;
    readonly attribute boolean   unique;
    void openObjectCursor (in optional IDBKeyRange range, in optional unsigned short direction) raises (IDBDatabaseException);
    void openCursor (in optional IDBKeyRange range, in optional unsigned short direction) raises (IDBDatabaseException);
    any  put (in any value, in optional any key);
    any  add (in any value, in optional any key) raises (IDBDatabaseException);
    any  getObject (in any key) raises (IDBDatabaseException);
    any  get (in any key) raises (IDBDatabaseException);
    void remove (in any key) raises (IDBDatabaseException);
};

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

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

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

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

[NoInterfaceObject]
interface IDBCursorSync {
    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;
    readonly attribute any                key;
             attribute any                value setraises (IDBDatabaseException);
    readonly attribute unsigned long long count;
    boolean continue (in optional any key);
    void    remove () raises (IDBDatabaseException);
};

[NoInterfaceObject]
interface IDBTransactionSync {
    attribute boolean         static;
    attribute IDBDatabaseSync db;
    IDBObjectStoreSync objectStore (in DOMString name) raises (IDBDatabaseException);
    void               abort () raises (IDBDatabaseException);
    void               commit () raises (IDBDatabaseException);
};

4.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 an optional 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. If a description is passed to these steps, set the description of db to that.
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.

4.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. Produce a structured clone of value and call it object.
5. If key is not defined or null, then perform the following steps.
   1. If store does not have a key generator, then terminate these steps and set error code NOT_ALLOWED_ERR.
   2. Using store's key generator, produce the next key and store it as key.
   3. If store uses in-line keys, then store key as the property value for object at store's key path.
6. 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.

7. 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.
8. Return the key.

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

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

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

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

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

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

4.9 Transaction Creation steps

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

1. Pick the appropriate steps:

   If these steps are called with the global flag set

   Acquire a lock on the entire database.

   If these steps are called with a non-empty list of object store names

   Acquire appropriate locks on each of the named object store in an ordered sequence.

   A user agent may obtain a shared or exclusive lock on the database if it does not perform fine grained locking.

2. 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.
3. Open a new transaction to the database, and create a IDBTransaction object that represents that transaction. Let transaction be this object.
4. Set the current transaction of this IDBDatabase object to transaction.
5. Return transaction. End these steps.
6. This step is only performed in case of error. If this step is performed synchronously, then raise a newly constructed IDBDatabaseException exception exception with the code code.

4.10 VERSION_CHANGE transaction steps

The steps for running a VERSION_CHANGE transaction are as follows. These steps must be run with three parameters - a database, a new version number to be set for the database and a request object representing the IDBRequest instance associated with this transaction.

1. Let openDatabases be the set of all IDBDatabase object representing the given database.
2. Fire a versionchange event targeted at each object in the openDatabases set. The version property of this event must be set to the given version number.
3. Wait until all objects in openDatabases are closed.
4. Start a new transaction with mode set to VERSION_CHANGE. Note that as long as this transaction is running, no other IDBDatabase objects can be open.
5. Set the version of the database to the given version number.
6. Fire a success event targeted at the request object. The result propety of the event should be set to a new IDBTransaction object representing the VERSION_CHANGE transaction created in step 4.
7. Follow the normal steps for executing a transaction and let the transaction complete normally.

4.11 Database closing steps

The steps for closing a database connection are as follows. These steps must be run with one parameter - a database object of type IDBDatabase.

1. Set the internal closePending flag of the database object to true. If the transaction() method is called on the database object while the closePending is set, an exception will be thrown.
2. Wait for all pending transactions on the database to complete. Once they are complete, the database is fully closed.
3. Unblock any pending setVersion() calls made on other IDBDatabase objects connected to the same database.

5.1 User tracking

A third-party host (or any object capable of getting content distributed to multiple sites) could use a unique identifier stored in its client-side database to track a user across multiple sessions, building a profile of the user's activities. In conjunction with a site that is aware of the user's real id object (for example an e-commerce site that requires authenticated credentials), this could allow oppressive groups to target individuals with greater accuracy than in a world with purely anonymous Web usage.

There are a number of techniques that can be used to mitigate the risk of user tracking:

Blocking third-party storage

User agents may restrict access to the database objects to scripts originating at the domain of the top-level document of the browsing context, for instance denying access to the API for pages from other domains running in iframes.

Expiring stored data

User agents may automatically delete stored data after a period of time.

This can restrict the ability of a site to track a user, as the site would then only be able to track the user across multiple sessions when he authenticates with the site itself (e.g. by making a purchase or logging in to a service).

However, this also puts the user's data at risk.

Treating persistent storage as cookies

User agents should present the database feature to the user in a way that associates them strongly with HTTP session cookies. [COOKIES]

This might encourage users to view such storage with healthy suspicion.

Site-specific white-listing of access to databases

User agents may require the user to authorize access to databases before a site can use the feature.

Origin-tracking of stored data

User agents may record the origins of sites that contained content from third-party origins that caused data to be stored.

If this information is then used to present the view of data currently in persistent storage, it would allow the user to make informed decisions about which parts of the persistent storage to prune. Combined with a blacklist ("delete this data and prevent this domain from ever storing data again"), the user can restrict the use of persistent storage to sites that he trusts.

Shared blacklists

User agents may allow users to share their persistent storage domain blacklists.

This would allow communities to act together to protect their privacy.

While these suggestions prevent trivial use of this API for user tracking, they do not block it altogether. Within a single domain, a site can continue to track the user during a session, and can then pass all this information to the third party along with any identifying information (names, credit card numbers, addresses) obtained by the site. If a third party cooperates with multiple sites to obtain such information, a profile can still be created.

However, user tracking is to some extent possible even with no cooperation from the user agent whatsoever, for instance by using session identifiers in URLs, a technique already commonly used for innocuous purposes but easily repurposed for user tracking (even retroactively). This information can then be shared with other sites, using using visitors' IP addresses and other user-specific data (e.g. user-agent headers and configuration settings) to combine separate sessions into coherent user profiles.

5.2 Cookie resurrection

If the user interface for persistent storage presents data in the persistent storage features described in this specification separately from data in HTTP session cookies, then users are likely to delete data in one and not the other. This would allow sites to use the two features as redundant backup for each other, defeating a user's attempts to protect his privacy.

5.3 Sensitivity of data

User agents should treat persistently stored data as potentially sensitive; it's quite possible for e-mails, calendar appointments, health records, or other confidential documents to be stored in this mechanism.

To this end, user agents should ensure that when deleting data, it is promptly deleted from the underlying storage.

6.1 DNS spoofing attacks

Because of the potential for DNS spoofing attacks, one cannot guarantee that a host claiming to be in a certain domain really is from that domain. To mitigate this, pages can use SSL. Pages using SSL can be sure that only pages using SSL that have certificates identifying them as being from the same domain can access their databases.

6.2 Cross-directory attacks

Different authors sharing one host name, for example users hosting content on geocities.com, all share one set of databases.

There is no feature to restrict the access by pathname. Authors on shared hosts are therefore recommended to avoid using these features, as it would be trivial for other authors to read the data and overwrite it.

Even if a path-restriction feature was made available, the usual DOM scripting security model would make it trivial to bypass this protection and access the data from any path.

6.3 Implementation risks

The two primary risks when implementing these persistent storage features are letting hostile sites read information from other domains, and letting hostile sites write information that is then read from other domains.

Letting third-party sites read data that is not supposed to be read from their domain causes information leakage, For example, a user's shopping wish list on one domain could be used by another domain for targeted advertising; or a user's work-in-progress confidential documents stored by a word-processing site could be examined by the site of a competing company.

Letting third-party sites write data to the persistent storage of other domains can result in information spoofing, which is equally dangerous. For example, a hostile site could add records to a user's wish list; or a hostile site could set a user's session identifier to a known ID that the hostile site can then use to track the user's actions on the victim site.

Thus, strictly following the origin model described in this specification is important for user security.