W3C

Indexed Database API

W3C Working Draft 19 August 2010

This version:
http://www.w3.org/TR/2010/WD-IndexedDB-20100819/
Latest published version:
http://www.w3.org/TR/IndexedDB/
Latest editor's draft:
https://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html
Previous version:
http://www.w3.org/TR/2010/WD-IndexedDB-20100105/
Editors:
Nikunj Mehta, Invited Expert
Jonas Sicking, Mozilla
Eliot Graff, Microsoft
Andrei Popescu, Google

Abstract

This document defines APIs for a database of records holding simple values and hierarchical objects. Each record consists of a key and some value. Moreover, the database maintains indexes over records it stores. An application developer directly uses an API to locate records either by their key or by using an index. A query language can be layered on this API. An indexed database can be implemented using a persistent B-tree data structure.

Status of This Document

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

This document was published by the Web Applications Working Group as a Working Draft. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

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

Table of Contents

1. Introduction

This section is non-normative.

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

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

Example

A script can efficiently find records in an object store that come closest to the required value provided the value is stored in either a primary or a secondary key. In the following example, the 'books' object store holds data about books which are stored by their 'isbn' attribute. Additionally, an index is maintained on the 'author' attribute of the objects stored in the object store. This index can be used to look up books for a given author. If an exact match is not found, the operation raises an exception.

ECMAScript
var db = indexedDB.open('books', 'Book store', false);
if (db.version !== '1.0') {
  var olddb = indexedDB.open('books', 'Book store');
  olddb.createObjectStore('books', 'isbn');
  olddb.createIndex('BookAuthor', 'books', 'author', false);
  olddb.setVersion("1.0");  
}
// db.version === "1.0";  
var index = db.openIndex('BookAuthor');
var matching = index.get('fred');
if (matching)
  report(matching.isbn, matching.name, matching.author);
else
  report(null);

The next example performs the exact same logic as above asynchronously.

ECMAScript

  function findFred() {
    var store = db.objectStore('books');
    var index = store.index('BookAuthor');
    var req = index.get('fred');
    req.onsuccess = function(event) {
      var matching = event.result;
      report(matching.isbn, matching.name, matching.author);
    }
    req.onerror = function(event) {
      report(null);
    }
  }

  var db;
  var dbRequest = indexedDB.open('books', 'Book store');
  dbRequest.onsuccess = function(event) {
    db = event.result;
    if (db.version != "1.0") {
      var versionRequest = db.setVersion("1.0");
      versionRequest.ontimeout = function(event) {
        throw new Error("timeout trying to set version to 1.0");
      }
      versionRequest.onsuccess = function(event) {
        var store = db.createObjectStore('books', 'isbn');
        store.createIndex('BookAuthor', 'books', 'author', false);
        event.transaction.onabort = function(event) {
          throw new Error("error while trying to set version to 1.0");
        }
        event.transaction.oncomplete = function(event) {
          findFred(db);
        }
      }
    } else {
      findFred(db);
    }
  }
   
        

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

This specification defines one class of products:

Conforming user agent

A user agent must behave as described in this specification in order to be considered conformant.

User agents may implement algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.

A conforming Indexed Database API user agent must also be a conforming implementation of the IDL fragments of this specification, as described in the “Web IDL” specification. [WEBIDL]

This specification uses both the terms "conforming user agent(s)" and "user agent(s)" to refer to this product class.

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. Indexed Database API

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.

3.1.1 Keys

In order to efficiently retrieve records stored in an indexed database, a user agent needs to organize each record according to its key. Conforming user agents must support the use of the following values as keys: IDL data types DOMString, long, and float [WEBIDL]; the Date JavaScript object [ECMA-262]; as well as the value null.

For purposes of comparison, all DOMString values are evaluated as greater than long, float, and Date values; Date values are evaluated as greater than long and float values; and long and float values are evaluated by their numeric value with no need to separate them by type. Moreover, null always evaluates less than any other key value that is a non-null value. For the particular case of floating point numbers, the value NaN is not allowed.

Only data types with natural ordering can be used as keys. The ECMAScript undefined must not be used as a 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 can 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 should be used to derive a key value.

3.1.3 Object Store

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

Every object store has a name. Within a database, each object store must have a valid and unique name.

If an object store uses keys generated from a monotonically increasing sequence, it must have a key generator that produces unique keys for records in that object store. Alternatively, if an application provides keys, they may 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 stored objects in that object store.

The IDBObjectStore and IDBObjectStoreSync interfaces provide access to the metadata of an object store.

3.1.4 Index

Records in an object store can be retrieved using the record's key. However, that may not always be 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. If an index's unique flag is set, then it must not allow duplicate values for a key. Every index has a name. Within an object store, each index must have a valid and unique 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. This key path must be the name of an enumerated property of every object to be stored in the object store referenced by that index. The auto-populated index record corresponding to an object store record must satisfy the following index maintenance conditions:

The IDBIndex and IDBIndexSync interfaces provide access to the metadata of an index.

3.1.5 Database

Each origin has an associated set of databases. A database comprises one or more object stores.

Each database has a valid name and a human readable description. A valid name is any string including the empty string. An exact match of names means that their UTF-8 encodings are identical.

If an implementation does not support all sets of strings, it may implement support for arbitrary strings by mapping database names (e.g. using a hashing algorithm) to the supported set of names.

Each database also has a current version.

Each database has one version at a time; a database can't exist in multiple versions at once.

The act of opening a database creates a database connection. There may be multiple connections to a given database at any given time. An operation that is attempting to read a given piece of data in a database is called a reader and one that is attempting to write a piece of data is called a writer. Readers and writers should only operate through transactions. A connection may have any number of active transactions.

IDBDatabase and IDBDatabaseSync interfaces represent connections to a database.

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 IDBKeyRange interface defines a key range.

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);
};
Attributes
flags of type unsigned short, readonly
Flags for bounding values
No exceptions.
left of type any, readonly
This value is the left-bound of the key range.
No exceptions.
right of type any, readonly
This value is the right-bound of the key range.
No exceptions.
Methods
bound
Create a new left- and right-bound key range.
ParameterTypeNullableOptionalDescription
leftanyThe left-bound value
rightanyThe right-bound value
openLeftbooleanIs the left-bound value included in the key range.
openRightbooleanIs the right-bound value included in the key range.
No exceptions.
Return type: IDBKeyRange
leftBound
Create a new left-bound key range.
ParameterTypeNullableOptionalDescription
boundanyThe left bound value
openbooleanIs the left-bound value included in the key range.
No exceptions.
Return type: IDBKeyRange
only
Create a new single-valued key range.
ParameterTypeNullableOptionalDescription
valueanyThe only value
No exceptions.
Return type: IDBKeyRange
rightBound
Create a new right-bound key range.
ParameterTypeNullableOptionalDescription
boundanyThe right bound value
openbooleanIs the right-bound value included in the key range.
No exceptions.
Return type: IDBKeyRange
Constants
LEFT_BOUND of type unsigned short
This flag indicates a left-bound key range.
LEFT_OPEN of type unsigned short
This flag indicates a left-open key range.
RIGHT_BOUND of type unsigned short
This flag indicates a right-bound key range.
RIGHT_OPEN of type unsigned short
This flag indicates a right-open key range.
SINGLE of type unsigned short
This flag indicates a single-valued key range.

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.

Cursor objects implement the IDBCursor or the IDBCursorSync interfaces.

3.1.8 Transaction

A transaction is defined on a database. A transaction's scope is either static or dynamic and it may include a subset of the object stores of the transaction's database. If the scope is static, then it may be global, meaning that it includes every existing and to be created object stores of the database. There may be multiple transactions active in a database as long as their scopes do not overlap or the overlapping objects are locked in modes that are not mutually exclusive.

TODO: decide what happens when dynamic transactions need to lock a database object that is already exclusively locked by another transaction.

Concurrent access to the object stores in a transaction may be isolated in one of three modes. These are:

  1. READ_ONLY
  2. READ_WRITE
  3. SNAPSHOT_READ
  4. VERSION_CHANGE

Any number of readers may concurrently access all object stores. A writer is not allowed if there is any reader concurrently accessing the object stores, unless the reader is detached, i.e., looking at a snapshot view of the data that does not change once created.

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. A transaction may be programmatically aborted. Conforming user agents must automatically:

  • commit a transaction at the end of the scope in which it was created unless there is an active operation being performed using that transaction, in which case, the transaction is automatically committed when that operation is completed.
  • abort a transaction at the end of the scope in which it was created, if an exception is propagated to that scope.

Static transaction objects implement the IDBTransaction or the IDBTransactionSync interfaces.

Dynamic transaction objects implement the IDBDynamicTransaction or the IDBDynamicTransactionSync interfaces.

Define dynamic transactions if we agree they should be part of this specification.

3.1.9 The IDBDatabaseException Interface

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;
};
Fields
code of type attribute unsigned short
Return the most appropriate error code.
message of type attribute DOMString
Return an error message describing the exception raised. The message should be localized to the user's language.
Constants
CONSTRAINT_ERR of type unsigned short
A mutation operation in the transaction failed due to a because a constraint was not satisfied. For example, an object such as an object store or index already exists and a new one was being attempted to be created.
DATA_ERR of type unsigned short
Data provided to an operation does not meet requirements.
DEADLOCK_ERR of type unsigned short
The current transaction was automatically rolled back by the database because of deadlock or other transaction serialization failures.
NON_TRANSIENT_ERR of type unsigned short
This error occurred because an operation was not allowed on an object. A retry of the same operation would fail unless the cause of the error is corrected.
NOT_ALLOWED_ERR of type unsigned short
A mutation operation was attempted on a database that did not allow mutations.
NOT_FOUND_ERR of type unsigned short
The operation failed because the requested database object could not be found. For example, an object store did not exist but was being opened.
RECOVERABLE_ERR of type unsigned short
The operation failed because the database was prevented from taking an action. The operation might be able to succeed if the application performs some recovery steps and retries the entire transaction. For example, there was not enough remaining storage space, or the storage quota was reached and the user declined to give more space to the database.
SERIAL_ERR of type unsigned short
The operation failed because of the size of the data set being returned or because there was a problem in serializing or deserializing the object being processed.
TIMEOUT_ERR of type unsigned short
A lock for the transaction could not be obtained in a reasonable time.
TRANSIENT_ERR of type unsigned short
The operation failed because of some temporary problems. The failed operation might be able to succeed when the operation is retried without any intervention by application-level functionality.
UNKNOWN_ERR of type unsigned short
The operation failed for reasons unrelated to the database itself and not covered by any other error code.

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.

3.2.1 Event interfaces

Events are fired during asynchronous access as database objects are created and data is consumed from these objects. As requests are made to database objects, the user agent loads information about them into memory and when the required object handle is available, it alerts the application through the firing of events. The events are as follows:

The IDBEvent interface extends the Event interface defined in [DOM-LEVEL-3-EVENTS].

[NoInterfaceObject]
interface IDBEvent : Event {
    readonly attribute any source;
};
Attributes
source of type any, readonly
Returns the asynchronous request object that fired this event.
No exceptions.
[NoInterfaceObject]
interface IDBSuccessEvent : IDBEvent {
    readonly attribute any result;
};
Attributes
result of type any, readonly
Returns the result of the successful completion of an asynchronous request on the source.
No exceptions.
[NoInterfaceObject]
interface IDBTransactionEvent : IDBSuccessEvent {
    readonly attribute IDBTransaction transaction;
};
Attributes
transaction of type IDBTransaction, readonly
Returns the transaction used for the request on the source.
No exceptions.
[NoInterfaceObject]
interface IDBErrorEvent : IDBEvent {
    readonly attribute unsigned short code;
    readonly attribute DOMString      message;
};
Attributes
code of type unsigned short, readonly
Returns the most appropriate error code from carrying out the asynchronous request on the source. The valid values of this error code are defined on the exception IDBDatabaseException.
No exceptions.
message of type DOMString, readonly
Returns the describing the reason for the error. The message should be localized to the user's language.
No exceptions.
[NoInterfaceObject]
interface IDBVersionChangeEvent : IDBEvent {
    readonly attribute DOMString version;
};
Attributes
version of type DOMString, readonly
Returns the new version of the database during a VERSION_CHANGE transaction. See the steps for running a VERSION_CHANGE transaction.
No exceptions.

3.2.2 The IDBRequest Interface

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

Example

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

ECMAScript

 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;
};
Attributes
onerror of type Function
The event handler for the error event
No exceptions.
onsuccess of type Function
The event handler for the success event
No exceptions.
readyState of type unsigned short, readonly
Every request starts in the LOADING state. When either the request completes, fails or aborts successfully, the state changes to DONE.
No exceptions.
Methods
abort
This method has no effect if the readyState is DONE. If made on a read request, the implementation discontinues the in-flight request even if the implementation has already read the data, and is ready to fire a success event. The error event is always fired if abort() is called, and the success event is suppressed. The readyState moves to DONE. If the request aborts successfully, the error is set to UNKNOWN_ERR.
No parameters.
No exceptions.
Return type: void
Constants
DONE of type unsigned short
This state indicates that a result to a previous request is available in the result attribute.
LOADING of type unsigned short
This state indicates that a request has been started but its results is not yet available.

When a request is made, the readyState changes to LOADING. If a request completes successfully, the readyState changes to DONE, the result of the request is included as the result of a new IDBSuccessEvent event, and queue a task to fire that event with the name success, with no namespace, which does not bubble, is not cancelable at each Window object.

If an error occurs while performing the operation, the readyState changes to DONE, the error code and message are included in a new IDBDatabaseError event, and queue a task to fire that event with the name error, with no namespace, which does not bubble, is not cancelable at each Window object.

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

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

Event handler Event handler event type Event interface(s)
onsuccess success IDBSuccessEvent, IDBTransactionEvent
onerror error IDBErrorEvent

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

Event handler Event handler event type
oncomplete complete
onabort abort
ontimeout timeout

3.2.3 Opening a database

Window and Worker objects must implement the IDBEnvironment interface.

Window implements IDBEnvironment;
Worker implements IDBEnvironment;
[NoInterfaceObject]
interface IDBEnvironment {
    readonly attribute IDBFactory indexedDB;
};
Attributes
indexedDB of type IDBFactory, readonly
This attribute provides applications a mechanism for accessing capabilities of indexed databases.
No exceptions.

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 or object handle at a time.

[NoInterfaceObject]
interface IDBFactory {
    readonly attribute DOMStringList databases;
    IDBRequest open (in DOMString name, in DOMString description) raises (IDBDatabaseException);
};
Attributes
databases of type DOMStringList, readonly
This value is the list of the names of databases available in the global scope object.
No exceptions.
Methods
open

This method returns immediately and runs the following steps in a different thread. If an error occurs while the database connection is being opened, then an error event is fired on this method's returned object with its code set to UNKNOWN_ERR and a suitable message.

  1. Let origin be the origin of the active document from which the method was invoked.
  2. Perform the steps for opening a database, with origin, the name parameter and description parameter, and call its result as result.
  3. If the steps were aborted with an error code, then set this request's error with that code and abort these steps.
  4. Create a IDBDatabase object for result and call it db.
  5. Fire a success event on this method's returned object using the IDBSuccessEvent interface with its result set to db.
ParameterTypeNullableOptionalDescription
nameDOMStringThe name for the database
descriptionDOMStringThe description for the database
ExceptionDescription
IDBDatabaseException
NON_TRANSIENT_ERRif the name parameter is not valid
Return type: IDBRequest

3.2.4 Database

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

[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 ();
};
Attributes
description of type DOMString, readonly
On getting, this attribute must return the description of the connected database at the time of opening.
No exceptions.
name of type DOMString, readonly
On getting, this attribute must return the name of the connected database.
No exceptions.
objectStores of type DOMStringList, readonly
On getting, this attribute must return a list of names of the object stores currently in the connected database.
No exceptions.
version of type DOMString, readonly
On getting, this attribute must return the version of this database. This attribute has the null value when the connected database is first created.
No exceptions.
Methods
close
This method returns immediately and performs the steps for closing a database connection.
No parameters.
No exceptions.
Return type: void
createObjectStore

This method creates and returns a new object store with the given name in the connected database. Note that this method must only be called from a VERSION_CHANGE transaction callback.

ParameterTypeNullableOptionalDescription
nameDOMStringThe name of a new object store
keyPathDOMStringThe key path of a new object store. If empty path is specified, then the object store created will not have a key path and will use out-of-line keys.
autoIncrementbooleanWhether the object store created should have a key generator. This defaults to true.
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis method was not called from a VERSION_CHANGE transaction callback.
CONSTRAINT_ERRAn object store with the same name, compared in a case-sensitive manner, already exists in the connected database.
Return type: IDBObjectStore
objectStore
This method implicitly creates a transaction and opens the object store with the given name in the connected database as the transaction's static scope.
ParameterTypeNullableOptionalDescription
nameDOMStringThe name of an existing object store
modeunsigned shortThe mode used to access the object store, which defaults to READ_ONLY.
timeoutunsigned longThe interval which this operation is allowed to take to reserve all the database objects identified in the new transaction's scope. The default is user agent specific.
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERRThere is no object store with the given name, compared in a case-sensitive manner, in the connected database.
Return type: IDBObjectStore
removeObjectStore

This method destroys the object store with the given name in the connected database as well as all indexes that are referencing that object store. Note that this method must only be called from a VERSION_CHANGE transaction callback.

ParameterTypeNullableOptionalDescription
nameDOMStringThe name of an existing object store
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis method was not called from a VERSION_CHANGE transaction callback.
NOT_FOUND_ERRThere is no object store with the given name, compared in a case-sensitive manner, in the connected database.
Return type: void
setVersion
This method returns immediately and sets the version of the connected database by following the steps for running a VERSION_CHANGE transaction.
ParameterTypeNullableOptionalDescription
versionDOMStringThe version to store in the database
No exceptions.
Return type: IDBRequest
transaction
This method returns an IDBTransaction object immediately and performs the steps for creating a transaction with either the list of object store names for acquiring locks required in this transaction or the global flag set to true, and an optional timeout duration. The global flag is set only if the list is either empty, not passed or passed as null. If reserving all the object stores identified in the requested scope takes longer than the specified timeout interval, then an timeout event is fired on this method's returned object with its code set to TIMEOUT_ERR and a suitable message.
ParameterTypeNullableOptionalDescription
storeNamesDOMStringListThe names of object stores and indexes in the scope of the new transaction
modeunsigned short The mode for isolating access to data inside the given object stores. If this parameter is not provided, the default access mode is READ_ONLY.
timeoutunsigned longThe interval, specified in milliseconds, which this operation is allowed to take to reserve all the database objects identified in the new transaction's scope. The default is user agent specific
ExceptionDescription
IDBDatabaseException
TIMEOUT_ERRThe required locks could not be acquired in the given timeout interval
NOT_ALLOWED_ERRThe close() method has been called on this IDBDatabase instance and its internal closePending flag is set.
Return type: IDBTransaction

3.2.5 Object Store

Object store objects implement the following interface:
[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);
};
Attributes
indexNames of type DOMStringList, readonly
On getting, provide a list of the names of indexes on objects in this object store.
No exceptions.
keyPath of type DOMString, readonly
On getting, provide the key path of this object store. If this attribute is null, the application must provide a key value for each modification operation.
No exceptions.
name of type DOMString, readonly
On getting, provide the name of this object store.
No exceptions.
Methods
add
This method returns immediately and stores the given value in this object store by following the steps for storing a record into an object store with the no-overwrite flag set. If the record can be successfully stored in the object store, then a success event is fired on this method's returned object using the IDBTransactionEvent interface with its result set to the key for the stored record and transaction set to the transaction in which this object store is opened. If a record exists in this object store for the key key parameter, then an error event is fired on this method's returned object with its code set to CONSTRAINT_ERR
ParameterTypeNullableOptionalDescription
valueanyThe value to be stored in the record
keyanyThe key used to identify the record, which defaults to null
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis object store is not in the scope of any existing transaction or the associated transaction mode is READ_ONLY or SNAPSHOT_READ.
DATA_ERRThis object store uses out-of-line keys and no key generator but the key parameter was not passed, or the object store uses in-line keys and no key generator but the value object does not have a property identified by the store's key path.
SERIAL_ERRThe data being stored could not be serialized by the internal structured cloning algorithm.
Return type: IDBRequest
createIndex

This creates and returns a new index with the given name and parameters in the connected database. Note that this method must only be called from a VERSION_CHANGE transaction callback.

ParameterTypeNullableOptionalDescription
nameDOMStringThe name of a new index
keyPathDOMStringThe key path used by the new index
uniquebooleanThe unique flag for the new index
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis method was not called from a VERSION_CHANGE transaction callback.
CONSTRAINT_ERRAn index with the same name, compared in a case-sensitive manner, already exists in the connected database.
Return type: IDBIndex
get
This method returns immediately and retrieves the value from this object store for the record corresponding to the given key by following the steps for retrieving a record from an object store. If the operation is successful, then the result of this object's request is set to the retrieved value. If a record did not exist in this object store for the key key parameter, then an error event is fired on this method's returned object with its code set to NOT_FOUND_ERR and a suitable message. If the record can be successfully retrieved from the object store, then a success event is fired on this method's returned object using the IDBTransactionEvent interface with its result set to the value of the retrieved record and transaction set to the transaction in which this object store is opened.
ParameterTypeNullableOptionalDescription
keyanyKey identifying the record to be retrieved
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis object store is not in the scope of any existing transaction.
Return type: IDBRequest
index

This method returns immediately and opens the index with the given name in the connected database.

ParameterTypeNullableOptionalDescription
nameDOMStringThe name of an existing index
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERRThere is no index with the given name, compared in a case-sensitive manner, in the connected database.
Return type: IDBIndex
openCursor
This method returns immediately and creates a cursor over the records of this object store. The range of this cursor matches the key range specified as the range parameter, or if that parameter is not specified or null, then the range includes all the records. If there is even a single record that matches the key range, then a success event is fired on this method's returned object with its result set to the IDBCursor object for that cursor. If no records match the key range, then an success event is fired on this method's returned object with its result set to null.
ParameterTypeNullableOptionalDescription
rangeIDBKeyRangeThe key range to use as the cursor's range
directionunsigned shortThe cursor's required direction
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis object store is not in the scope of any existing transaction.
Return type: IDBRequest
put
This method returns immediately and stores the given value in this object store by following the steps for storing a record into an object store. If the record can be successfully stored in the object store, then a success event is fired on this method's returned object using the IDBTransactionEvent interface with its result set to the key for the stored record and transaction set to the transaction in which this object store is opened.
ParameterTypeNullableOptionalDescription
valueanyThe value to be stored in the record
keyanyThe key used to identify the record, which defaults to null
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis object store is not in the scope of any existing transaction or the associated transaction mode is READ_ONLY or SNAPSHOT_READ.
DATA_ERRThis object store uses out-of-line keys and no key generator but the key parameter was not passed, or the object store uses in-line keys and no key generator but the value object does not have a property identified by the store's key path.
SERIAL_ERRThe data being stored could not be serialized by the internal structured cloning algorithm.
Return type: IDBRequest
remove
This method returns immediately and removes the record from this object store by following the steps for deleting a record from an object store corresponding to the given key. If a record did not exist in this object store for the key parameter, then an error event is fired on this method's returned object with its code set to NOT_FOUND_ERR and a suitable message. If the record can be successfully removed from the object store, then a success event is fired on this method's returned object using the IDBTransactionEvent interface with its result set to the value of the removed record and transaction set to the transaction in which this object store is opened.
ParameterTypeNullableOptionalDescription
keyanyKey identifying the record to be removed
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis object store is not in the scope of any existing transaction or the associated transaction mode is READ_ONLY or SNAPSHOT_READ.
Return type: IDBRequest
removeIndex

This method destroys the index with the given name in the connected database. Note that this method must only be called from a VERSION_CHANGE transaction callback.

ParameterTypeNullableOptionalDescription
indexNameDOMStringThe name of an existing index
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis method was not called from a VERSION_CHANGE transaction callback.
NOT_FOUND_ERRThere is no index with the given name, compared in a case-sensitive manner, in the connected database.
Return type: void

3.2.6 Index

Index objects implement the following interface:

[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);
};
Attributes
keyPath of type DOMString, readonly
On getting, provide the key path of this index. If this attribute is null, this index is not auto-populated.
No exceptions.
name of type DOMString, readonly
On getting, provide the name of this index.
No exceptions.
storeName of type DOMString, readonly
On getting, provide the name of this index's referenced object store.
No exceptions.
unique of type boolean, readonly
On getting, provide the unique flag of this index.
No exceptions.
Methods
get
This method returns immediately and retrieves the value from this index for the record corresponding to the given key parameter by following the steps for retrieving a value from an index. If the operation is successful, then the result of this object's request is set to the retrieved value. If a record did not exist in this index for the key key parameter, then an error event is fired on this method's returned object with its code set to NOT_FOUND_ERR and a suitable message.
ParameterTypeNullableOptionalDescription
keyanyKey identifying the record to be retrieved
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis object store is not in the scope of any existing transaction.
Return type: IDBRequest
getObject
This method returns immediately and retrieves the value from this index's referenced object store for the record corresponding to the given key by following the steps for retrieving a record from an index. If the operation is successful, then the result of this object's request is set to the retrieved value. If a record did not exist in this index for the key key parameter, then an error event is fired on this method's returned object with its code set to NOT_FOUND_ERR and a suitable message.
ParameterTypeNullableOptionalDescription
keyanyKey identifying the record to be retrieved
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis object store is not in the scope of any existing transaction.
Return type: IDBRequest
openCursor
This method returns immediately and creates a cursor over the records of this index. The range of this cursor matches the key range specified as the range parameter, or if that parameter is not specified or null, then the range includes all the records. If there is even a single record that matches the key range, then a success event is fired on this method's returned object with its result set to the IDBCursor object for that cursor. If no records match the key range, then an error event is fired on this method's returned object with its code set to NOT_FOUND_ERR and a suitable message.
ParameterTypeNullableOptionalDescription
rangeIDBKeyRangeThe key range to use as the cursor's range
directionunsigned shortThe cursor's required direction
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis object store is not in the scope of any existing transaction.
Return type: IDBRequest
openObjectCursor
This method returns immediately and creates a cursor over the records of this index's referenced object store as arranged by this index. The range of this cursor matches the key range specified as the range parameter, or if that parameter is not specified or null, then the range includes all the records. If there is even a single record that matches the key range, then a success event is fired on this method's returned object with its result set to the IDBCursor object for that cursor. If no records match the key range, then an error event is fired on this method's returned object with its code set to NOT_FOUND_ERR and a suitable message.
ParameterTypeNullableOptionalDescription
rangeIDBKeyRangeThe key range to use as the cursor's range
directionunsigned shortThe cursor's required direction
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis object store is not in the scope of any existing transaction.
Return type: IDBCursor

3.2.7 Cursor

Cursor objects implement the following interface:

[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);
};
Attributes
count of type unsigned long long, readonly
On getting, provide the approximate number of objects in the cursor.
No exceptions.
direction of type unsigned short, readonly
On getting, provide the traversal direction of the cursor.
No exceptions.
key of type any, readonly
The key for the record at the cursor's position.
No exceptions.
value of type any, readonly
The value for the record at the cursor's position.
No exceptions.
Methods
continue
This method returns immediately and advances the cursor to the next position along its direction to the item whose key matches the optional parameter. If no such parameter is provided, advance to the immediate next position. If the cursor has reached the end of its range, then an success event is fired on this method's returned object with its result set to null.
ParameterTypeNullableOptionalDescription
keyanyThe next key to position this cursor at
No exceptions.
Return type: boolean
remove

This method returns immediately and deletes the object at the cursor's position. The cursor's position is not changed. Any attempts to retrieve the cursor's current value will return null.

No parameters.
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis object store is not in the scope of any existing transaction or the associated transaction mode is READ_ONLY or SNAPSHOT_READ.
Return type: IDBRequest
update
This method returns immediately and sets the value for the record at the cursor's position.
ParameterTypeNullableOptionalDescription
valueany
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThis object store is not in the scope of any existing transaction or the associated transaction mode is READ_ONLY or SNAPSHOT_READ.
DATA_ERR The underlying object store uses in-line keys and the property at the key path does not match the key in this cursor's position.
SERIAL_ERRThe data being stored could not be serialized by the internal structured cloning algorithm.
Return type: IDBRequest
Constants
NEXT of type unsigned short
indicates that this cursor should yield all records, including duplicates and its direction is monotonically increasing order of keys.
NEXT_NO_DUPLICATE of type unsigned short
indicates that this cursor should yield all records, not including duplicates and its direction is monotonically increasing order of keys. For every key with duplicate values, only the first record is yielded.
PREV of type unsigned short
indicates that cursor should yield all records, including duplicates and its direction is monotonically decreasing order of keys.
PREV_NO_DUPLICATE of type unsigned short
indicates that this cursor should yield all records, not including duplicates and its direction is monotonically decreasing order of keys. For every key with duplicate values, only the first record is yielded.

3.2.8 Transaction

Static transaction objects implement the following interface:

[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;
};
Attributes
db of type IDBDatabase, readonly
The database connection of which this transaction is a part
No exceptions.
mode of type unsigned short, readonly
On getting, provide the mode for isolating access to data inside the object stores that are in the scope of the transaction.
No exceptions.
onabort of type Function
The event handler for the onabort event.
No exceptions.
oncomplete of type Function
The event handler for the oncomplete event.
No exceptions.
ontimeout of type Function
The event handler for the ontimeout event.
No exceptions.
Methods
abort
This method returns immediately and undoes all the changes performed to the objects of this database in this transaction. If this transaction has already been committed or aborted, then an error event is fired on this method's returned object with its code set to NON_TRANSIENT_ERR and a suitable message.
No parameters.
No exceptions.
Return type: void
objectStore
Immediately returns the object store that has been already added to the scope of this transaction.
ParameterTypeNullableOptionalDescription
nameDOMStringThe requested object store
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERR If the requested object store is not in this transaction's scope.
Return type: IDBObjectStore
Constants
READ_ONLY of type unsigned short
Modification operations are not allowed in the transaction in this mode.
READ_WRITE of type unsigned short
Modification operations are allowed in the transactions in this mode.
SNAPSHOT_READ of type unsigned short
This mode is used solely for reading from a snapshot of the data in the object stores that are in the scope of the transaction.
VERSION_CHANGE of type unsigned short
This mode is used solely for updating the version number of transactions started using the setVersion() method of IDBDatabase.

Dynamic transaction objects implement the following interface:

[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;
};
Attributes
db of type IDBDatabase, readonly
The database connection of which this transaction is a part.
No exceptions.
onabort of type Function
The event handler for the onabort event.
No exceptions.
oncomplete of type Function
The event handler for the oncomplete event.
No exceptions.
ontimeout of type Function
The event handler for the ontimeout event.
No exceptions.
Methods
abort
This method returns immediately and undoes all the changes performed to the objects of this database in this transaction. If this transaction has already been committed or aborted, then an error event is fired on this method's returned object with its code set to NON_TRANSIENT_ERR and a suitable message.
No parameters.
No exceptions.
Return type: void
openObjectStore
Returns immediately and then attempts to lock the requesed object store in the given mode.
ParameterTypeNullableOptionalDescription
nameDOMStringThe requested object store.
modeunsigned shortThe mode for isolating access to the object store, which defaults to READ_ONLY.
No exceptions.
Return type: IDBRequest

Finish the dynamic transaction IDL and define the behavior of dynamic transactions.

3.3 Synchronous APIs

3.3.1 Opening a database

Worker objects must implement the IDBEnvironmentSync interface.

WorkerUtils implements IDBEnvironmentSync;
[NoInterfaceObject]
interface IDBEnvironmentSync {
    readonly attribute IDBFactorySync indexedDBSync;
};
Attributes
indexedDBSync of type IDBFactorySync, readonly
This attribute provides applications a mechanism for accessing capabilities of indexed databases.
No exceptions.
[NoInterfaceObject]
interface IDBFactorySync {
    IDBDatabaseSync open (in DOMString name, in DOMString description) raises (IDBDatabaseException);
};
Methods
open

The synchronous API for databases blocks the calling thread until a IDBDatabaseSync object is ready to return. When this method is invoked, the user agent must run the following steps:

  1. Let origin be the origin of the scripts in the worker.
  2. Perform the steps for opening a database, with origin, the name parameter and description parameter, and call its result as result.
  3. If the steps were aborted with an error code, then throw a newly constructed IDBDatabaseException exception with the code of that error and abort these steps.
  4. Create a IDBDatabaseSync object using result and call it db.
  5. Return db.
ParameterTypeNullableOptionalDescription
nameDOMStringThe name for the database
descriptionDOMStringThe description for the database
ExceptionDescription
IDBDatabaseException
UNKNOWN_ERRif an error occurs while the database connection is being opened
NON_TRANSIENT_ERRif the name parameter is not valid
Return type: IDBDatabaseSync

3.3.2 Database

[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);
};
Attributes
description of type DOMString, readonly
On getting, this attribute must return the description of the connected database at the time of opening.
No exceptions.
name of type DOMString, readonly
On getting, this attribute must return the name of the connected database.
No exceptions.
objectStores of type DOMStringList, readonly
On getting, this attribute must return a list of names of the object stores currently in the connected database.
No exceptions.
version of type DOMString, readonly
On getting, this attribute must return the version of this database. This attribute has the null value when the connected database is first created.
No exceptions.
Methods
createObjectStore

This method creates a and returns a new object store with the given name in the connected database.

ParameterTypeNullableOptionalDescription
nameDOMStringThe name of a new object store
keyPathDOMStringThe key path of a new object store. If null path is specified, then the object store created will not have a key path and will use out-of-line keys.
autoIncrementbooleanWhether the object store created should have a key generator. The default value of this parameter is false.
ExceptionDescription
IDBDatabaseException
CONSTRAINT_ERR If an object store with the same name, compared in a case-sensitive manner, already exists in the connected database.
Return type: IDBObjectStoreSync
openObjectStore

This method opens the object store with the given name in the connected database for the mode specified.

ParameterTypeNullableOptionalDescription
nameDOMStringThe name of an existing object store
modeunsigned shortThe mode used to access the object store. The default for this is IDBObjectStore.READ_WRITE
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERR If an object store with the same name, compared in a case-sensitive manner, already exists in the connected database.
Return type: IDBObjectStoreSync
removeObjectStore

This method destroys an object store with the given name as well as all indexes that are referencing that object store.

ParameterTypeNullableOptionalDescription
storeNameDOMStringThe name of an existing object store
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERR If the object store with the given name, compared in a case-sensitive manner, does not already exist in the connected database.
Return type: void
setVersion
This method sets the version of the connected database.
ParameterTypeNullableOptionalDescription
versionDOMStringThe version to store in the database
No exceptions.
Return type: void
transaction
Perform the steps for creating a transaction with the list of database objects in the scope of this transaction and a timeout duration in milliseconds, and return the resulting IDBTransactionSync object.
ParameterTypeNullableOptionalDescription
storeNamesDOMStringListThe names of object stores and indexes in the scope of the new transaction
timeoutunsigned longThe interval in milliseconds which this operation is allowed to take to reserve all the database objects identified in the new transaction's scope. The default is user agent specific
ExceptionDescription
IDBDatabaseException
TIMEOUT_ERR If reserving all the database objects identified in the new transaction's scope takes longer than the specified interval.
Return type: IDBTransactionSync

3.3.3 Object Store

Example

In the following example, we set up an object store to use the key path id. This object store is also designed to use a key generator.

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

Using this database, we can store records in the Contact object store.

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

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

A stored value can be retrieved using the same key used by the first put operation.

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

A second put operation will overwrite the record stored by the first put operation.

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

Now when the object store is read with the same key, the result is different compared to the object read earlier.

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

Additionally, all the records of an object store matching a certain key range can be retrieved in key order.

ECMAScript
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);
};
Attributes
indexNames of type DOMStringList, readonly
On getting, provide a list of the names of indexes on objects in this object store.
No exceptions.
keyPath of type DOMString, readonly
On getting, provide the key path of this object store. If this attribute is null, the application must provide a key value for each modification operation.
No exceptions.
mode of type unsigned short, readonly
On getting, provide the mode for isolating access to data inside this object store.
No exceptions.
name of type DOMString, readonly
On getting, provide the name of this object store.
No exceptions.
Methods
add
Store the given value in this object store by following the steps for storing a record into an object store with the no-overwrite flag set. The returned object from this method is the key for the stored record.
ParameterTypeNullableOptionalDescription
valueanyThe value to be stored in the record
keyanyThe key used to identify the record
ExceptionDescription
IDBDatabaseException
DATA_ERRThis object store uses out-of-line keys and no key generator but the key parameter was not passed
SERIAL_ERRThe data being stored could not be serialized by the internal structured cloning algorithm
CONSTRAINT_ERRA record exists in this object store for the key key parameter.
Return type: any
createIndex

This method creates a and returns a new index with the given name in the connected database.

ParameterTypeNullableOptionalDescription
nameDOMStringThe name of a new index
keyPathDOMStringThe key path used by the new index
uniquebooleanThe unique flag for the new index. The default value of this parameter is false.
No exceptions.
Return type: IDBIndexSync
get
Retrieve the value from this object store for the record corresponding to the given key by following the steps for retrieving a record from an object store. The value returned from this method is the retrieved value.
ParameterTypeNullableOptionalDescription
keyanyKey identifying the record to be retrieved
ExceptionDescription
IDBDatabaseException
SERIAL_ERRThe data being stored could not be deserialized by the internal structured cloning algorithm
NOT_FOUND_ERRA record did not exist in this object store for the key key parameter.
Return type: any
openCursor
Create a cursor over the records of this object store. The range of this cursor matches the key range specified as the range parameter, or if that parameter is not specified or null, then the range includes all the records.
ParameterTypeNullableOptionalDescription
rangeIDBKeyRangeThe key range to use as the cursor's range
directionunsigned shortThe cursor's required direction
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERRNo records exist in this object store for the requested key range.
Return type: IDBCursorSync
openIndex

This method opens the index with the given name in the connected database for the mode specified.

ParameterTypeNullableOptionalDescription
nameDOMStringThe name of an existing index
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERR If the index with the given name does not exist in the connected database.
Return type: IDBIndexSync
put
Store the given value in this object store by following the steps for storing a record into an object store. The returned object from this method is the key for the stored record.
ParameterTypeNullableOptionalDescription
valueanyThe value to be stored in the record
keyanyThe key used to identify the record
ExceptionDescription
IDBDatabaseException
DATA_ERRThis object store uses out-of-line keys and no key generator but the key parameter was not passed
SERIAL_ERRThe data being stored could not be serialized by the internal structured cloning algorithm
Return type: any
remove
Remove the record from this object store by following the steps for deleting a record from an object store corresponding to the given key.
ParameterTypeNullableOptionalDescription
keyanyKey identifying the record to be removed
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERRA record did not exist in this object store for the key key parameter.
Return type: void
removeIndex

This method destroys an index with the given name.

ParameterTypeNullableOptionalDescription
indexNameDOMStringThe name of an existing index
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERR If the index with the given name does not exist in the connected database.
Return type: void
Constants
READ_ONLY of type unsigned short
Modification operations are not allowed on the object store in this mode.
READ_WRITE of type unsigned short
Modification operations are allowed on the object store in this mode.
SNAPSHOT_READ of type unsigned short
This mode is used solely for reading from a snapshot of the data in the object store.

3.3.4 Index

Example

An index can be created for retrieving records other than by using record keys. Continuing the earlier example, an auto-populated index could be maintained on the name property of objects in the Contact object store.

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

For example, the id of an object with the name property value 'Lincoln' can be retrieved using the ContactName index.

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

Additionally, all the records of an object store matching a certain range index keys can be retrieved in key order. When objects are retrieved from the Contact object store, they are arranged by the value of the id attribute. On the other hand, when objects are retrieved using the ContactName index, they are arranged by the value of the name property.

ECMAScript
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();

If, on the other hand, we only want the names but not the Contact objects for a given range, then we can use a different mechanism for that.

ECMAScript
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);
};
Attributes
keyPath of type DOMString, readonly
On getting, provide the key path of this index. If this attribute is null, this index is not auto-populated.
No exceptions.
name of type DOMString, readonly
On getting, provide the name of this index.
No exceptions.
storeName of type DOMString, readonly
On getting, provide the name of this index's referenced object store.
No exceptions.
unique of type boolean, readonly
On getting, provide the unique flag of this index.
No exceptions.
Methods
add
Store the given value in this index by following the steps for storing a record into an index and the no-overwrite flag set. The returned object from this method is the key for the stored record.
ParameterTypeNullableOptionalDescription
valueanyThe value to be stored in the record
keyanyThe key used to identify the record
ExceptionDescription
IDBDatabaseException
CONSTRAINT_ERR A record exists in this index for the key key parameter or this index is auto-populated or if no record exists with key value parameter in the index's referenced object store.
Return type: any
get
Retrieve the value from this index for the record corresponding to the given key by following the steps for retrieving a value from an index. The value returned from this method is the retrieved value.
ParameterTypeNullableOptionalDescription
keyanyKey identifying the record to be retrieved
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERRA record did not exist in this index for the key key parameter.
Return type: any
getObject
Retrieve the value from this index's referenced object store for the record corresponding to the given key by following the steps for retrieving a record from an index. The value returned from this method is the retrieved value.
ParameterTypeNullableOptionalDescription
keyanyKey identifying the record to be retrieved
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERRA record did not exist in this index for the key key parameter.
Return type: any
openCursor
Create a cursor over the records of this index. The range of this cursor matches the key range specified as the range parameter, or if that parameter is not specified or null, then the range includes all the records.
ParameterTypeNullableOptionalDescription
rangeIDBKeyRangeThe key range to use as the cursor's range
directionunsigned shortThe cursor's required direction
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERRNo records exist in this index for the requested key range.
Return type: void
openObjectCursor
Create a cursor over the records of this index's referenced object store as arranged by this index. The range of this cursor matches the key range specified as the range parameter, or if that parameter is not specified or null, then the range includes all the records.
ParameterTypeNullableOptionalDescription
rangeIDBKeyRangeThe key range to use as the cursor's range
directionunsigned shortThe cursor's required direction
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERRNo records exist in this index for the requested key range.
Return type: void
put
Store the given value in this index by following the steps for storing a record into an index. The returned object from this method is the key for the stored record.
ParameterTypeNullableOptionalDescription
valueanyThe value to be stored in the record
keyanyThe key used to identify the record
No exceptions.
Return type: any
remove
Remove the records from this index by following the steps for deleting a record from an index corresponding to the given key.
ParameterTypeNullableOptionalDescription
keyanyKey identifying the record to be removed
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERRA record did not exist in this index for the key key parameter.
Return type: void

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.

Example

By default, a cursor walks over objects starting at the first record and ending at the last record including all the duplicates encountered along the way. If the cursor callback returns true, then the iteration is stopped.

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

To start at the last record and end in the first record, the cursor should be created with the direction parameter PREV.

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

To start at a certain key and end in the last record, i.e., for a lower-bounded cursor, while skipping duplicates, the cursor should be created with both the required start key and the direction parameter.

ECMAScript
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();

It is also possible to create a bounded cursor, i.e., with application-specified starting and ending points, the cursor should be created with both the required keys. If the range is inclusive of both keys, then additional flags are required. In the following example, all keys with values in the inclusive range (start, end) are returned with all their duplicates, from the beginning of the range to its end.

ECMAScript
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);
};
Attributes
count of type unsigned long long, readonly
On getting, provide the approximate number of objects in the cursor.
No exceptions.
direction of type unsigned short, readonly
On getting, provide the traversal direction of the cursor.
No exceptions.
key of type any, readonly
The key for the record at the cursor's position.
No exceptions.
value of type any
The value for the record at the cursor's position.
ExceptionOn GetOn SetDescription
IDBDatabaseException
DATA_ERRIf the underlying object store uses in-line keys and the property at the key path does not match the key in this cursor's position.
SERIAL_ERRThe data being stored could not be serialized by the internal structured cloning algorithm
NOT_ALLOWED_ERRThe underlying index or object store does not support updating the item because it is open in the READ_ONLY or SNAPSHOT_READ mode.
NOT_ALLOWED_ERRAn index record cannot be changed because the underlying index is auto-populated.
Methods
continue
Advance the cursor to the next position along its direction to the item whose key matches the optional parameter. If no such parameter is provided, advance to the immediate next position. If the cursor has reached the end of its range, then this method returns false, otherwise it returns true.
ParameterTypeNullableOptionalDescription
keyanyThe next key to position this cursor at
No exceptions.
Return type: boolean
remove

Delete the object at the cursor's position. The cursor's position is not changed. Any attempts to retrieve the cursor's current value will return null.

No parameters.
ExceptionDescription
IDBDatabaseException
NOT_ALLOWED_ERRThe underlying index or object store does not support updating the item because it is open in the READ_ONLY or SNAPSHOT_READ mode.
Return type: void
Constants
NEXT of type unsigned short
indicates that this cursor should yield all records, including duplicates and its direction is monotonically increasing order of keys.
NEXT_NO_DUPLICATE of type unsigned short
indicates that this cursor should yield all records, not including duplicates and its direction is monotonically increasing order of keys. For every key with duplicate values, only the first record is yielded.
PREV of type unsigned short
indicates that cursor should yield all records, including duplicates and its direction is monotonically decreasing order of keys.
PREV_NO_DUPLICATE of type unsigned short
indicates that this cursor should yield all records, not including duplicates and its direction is monotonically decreasing order of keys. For every key with duplicate values, only the first record is yielded.

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.

[NoInterfaceObject]
interface IDBTransactionSync {
    attribute boolean         static;
    attribute IDBDatabaseSync db;
    IDBObjectStoreSync objectStore (in DOMString name) raises (IDBDatabaseException);
    void               abort () raises (IDBDatabaseException);
    void               commit () raises (IDBDatabaseException);
};
Attributes
db of type IDBDatabaseSync
The database connection of which this transaction is a part
No exceptions.
static of type boolean
If true, then this transaction is static and false otherwise.
No exceptions.
Methods
abort
This method signals the need to cancel the effects of operations performed in this transaction. To perform this method, the user agent ignores all the changes performed to the objects of this database since the creation of this transaction.
No parameters.
ExceptionDescription
IDBDatabaseException
NON_TRANSIENT_ERRIf this transaction has already been committed or aborted.
Return type: void
commit
This method signals the normal and satisfactory completion of a transaction. At this point, the user agent should durably store all the changes performed to the objects of this database since the creation of this transaction.
No parameters.
ExceptionDescription
IDBDatabaseException
RECOVERABLE_ERRIf this transaction's scope is dynamic, and the user agent cannot commit all the changes due to another transaction.
NON_TRANSIENT_ERRIf this transaction has already been committed or aborted.
Return type: void
objectStore
Immediately returns the object store that has been already added to the scope of this transaction.
ParameterTypeNullableOptionalDescription
nameDOMStringThe requested object store
ExceptionDescription
IDBDatabaseException
NOT_FOUND_ERR If the requested object store is not in this transaction's scope.
Return type: IDBObjectStoreSync
Applications must not assume that committing the transaction produces an instantaneously durable result. The user agent may delay flushing data to durable storage until an appropriate time.

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.

4. Algorithms

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.

Add steps for creating dynamic transactions.

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

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

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.

A. Requirements

Requirements will be written with an aim to verify that these were actually met by the API specified in this document.

B. Acknowledgements

The editor of this specification was employed by Oracle Corp during its early drafts.
Garret Swart was extremely influential in the design of this specification. Feedback from Margo Seltzer, Jonas Sicking, Arun Ranganathan, Shawn Wilsher, Pablo Castro, Kris Zyp, Chris Anderson, and Dana Florescu have led to improvements to this specification over time.

C. References

C.1 Normative references

[COOKIES]
Adam Barth. HTTP State Management Mechanism. IETF, November 2009
[DOM-LEVEL-3-EVENTS]
Björn Höhrmann; Tom Pixley; Philippe Le Hégaret. Document Object Model (DOM) Level 3 Events Specification. 21 December 2007. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071221
[ECMA-262]
ECMAScript Language Specification, Third Edition. December 1999. URL: http://www.ecma-international.org/publications/standards/Ecma-262.htm
[HTML5]
Ian Hickson; David Hyatt. HTML 5. 4 March 2010. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2010/WD-html5-20100304/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219
[WEBWORKERS]
Ian Hickson. Web Workers. 22 December 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-workers-20091222/

C.2 Informative references

[WEBSTORAGE]
Ian Hickson. Web Storage. 10 September 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-webstorage-20090910/