WebSimpleDB API

2.1. Dependencies

This specification relies on several other underlying specifications.

HTML5

Many fundamental concepts from HTML5 are used by this specification. [HTML5]

WebWorkers

This specification adds capabilities to WebWorkers and uses certain concepts defined in this specification. [WebWorkers]

3.1. Opening a database

[Supplemental] 
interface Environment {
  Database openDatabase(in DOMString name, 
                        in DOMString version, 
                        in DOMString displayName, 
                        in optional boolean readonly, 
                        in optional DatabaseCallback upgradeCallback);
};

Window implements Environment;

[Callback=FunctionOnly, NoInterfaceObject]
interface DatabaseCallback {
  void handleEvent(in Database database);
};

[Supplemental]
interface EnvironmentSync {
  DatabaseSync openDatabaseSync(in DOMString name, 
                        in DOMString version, 
                        in DOMString displayName, 
                        in optional boolean readonly, 
                        in optional DatabaseCallback upgradeCallback);
};

WorkerUtils implements Environment;
WorkerUtils implements EnvironmentSync;

The openDatabase() and the openDatabaseSync() methods take the following arguments: a database name, a database version, a display name, a read only flag, and optionally a callback to be invoked if the database has not yet been created. The callback, if provided, is intended to be used to call changeVersion(); the callback is invoked with the database having the empty string as its version regardless of the given database version. If the callback is not provided, the database is created with the given database version as its version.

When invoked, these methods must run the following steps, with all but the last two steps being run atomically:

1. For the method on the Window object: let origin be the origin of the active document of the browsing context of the Window object on which the method was invoked.

   For the methods on the WorkerUtils object: let origin be the origin of the scripts in the worker.

2. If the database version provided is not the empty string, and there is already a database with the given name from the origin origin, but the database has a different version than the version provided, then throw an INVALID_STATE_ERR exception and abort these steps.

3. If no database with the given name from the origin origin exists, then create the database and let created be true. Otherwise, let created be false.

   If a callback was passed to the method, then let the database's version be the empty string. Otherwise, let its version be the given database version.

4. For the openDatabase() method: let result be a newly constructed Database object representing the database with the given database name from the origin origin.

   For the openDatabaseSync() method: let result be a newly constructed DatabaseSync object representing the database with the given database name from the origin origin.

5. If created is false or if no callback was passed to the method, skip this step. Otherwise:
   • For the openDatabase() method: queue a task to to invoke the callback with result as its only argument.
   • For the openDatabaseSync() method: invoke the callback with result as its only argument. If the callback throws an exception, rethrow that exception and abort these steps.
6. Return result.

All strings including the empty string are valid database names. Database names must be compared in a case-sensitive manner.

The version that the database was opened with is the expected version of this Database or DatabaseSync object. It can be the empty string, in which case there is no expected version — any version is fine.

User agents are expected to use the display name to optimize the user experience.

3.2. Database

Two variants of databases are available in this API. The asynchronous version Database is available to both Window and WorkerUtils objects. The synchronous version DatabaseSync is available only to the WorkerUtils object.

interface AbstractDatabase {
  readonly attribute DOMString version;
  readonly attribute boolean mutable;
};

On getting, the version attribute must return the current version of the database (as opposed to the expected version of the AbstractDatabase object).

On getting, the mutable attribute must return whether the database can be modified. This is set at the time the database is opened.

interface Database : AbstractDatabase {
  transaction(in TransactionCallback txnCallback,
              in optional TransactionErrorCallback errorCallback,
              in optional DatabaseVoidCallback txnCallback,
              in optional Transaction parent,
              in optional unsigned short isolationLevel,
              in optional unsigned int timeout);
};

[Callback=FunctionOnly, NoInterfaceObject]
interface TransactionCallback {
  void handleEvent(in Transaction txn);
};

[Callback=FunctionOnly, NoInterfaceObject]
interface DatabaseVoidCallback {
  void handleEvent();
};

[Callback=FunctionOnly, NoInterfaceObject]
interface DatabaseTransactionErrorCallback {
  void handleEvent(in DatabaseError error);
};

interface DatabaseSync : AbstractDatabase {
  Transaction transaction(in optional Transaction parent,
              in optional unsigned short isolationLevel,
              in optional unsigned int timeout);
};

The transaction() method must run the following steps:

1. Create a Transaction object. Let transaction be the newly created Transaction object.
2. Return transaction.
3. For each call on transaction, perform the following steps
   1. If the call mutates the database, but transaction is on a read-only database, jump to the "in case of error" steps below.
   2. Execute the call in the context of the transaction.
   3. If the call failed, jump to the "in case of error" steps below.

   In case of error (or more specifically, if the above sub-steps say to jump to the "in case of error" steps), run the following substeps:

   1. If the call caused an error then throw a newly constructed DatabaseException exception that represents the error that caused these substeps to be run.

3.3. Transaction

A transaction represents an atomic, consistent, isolated, and durable set of database access and mutation operations. Transactions offer data protection from application or system failures.

• Atomicity

  Multiple database operations are treated as a single unit of work. Once committed, all write operations performed under the protection of the transaction are saved to the databases. Further, in the event that a transaction is aborted, all write operations performed during the transaction are discarded. In this event, the database is left in the state it was in before the transaction began, regardless of the number or type of write operations that may have been performed during the course of the transaction.

• Consistency

  Databases will never see a partially completed transaction. This is true even if the application fails while there are in-progress transactions. If the application or system fails, then either all of the database changes appear when the application next runs, or none of them appear.

• Isolation

  While a transaction is in progress, databases appear to the transaction as if there are no other operations occurring outside of the transaction. That is, operations wrapped inside a transaction will always have a clean and consistent view of the database. They never have to see updates currently in progress under the protection of another transaction. Note, however, that isolation guarantees can be increased and relaxed from the default setting.

• Durability

  Once committed to a database, modifications will persist even in the event of an application or system failure. Note that like isolation, durability guarantees can be relaxed by a user preference or user agent configuration.

var database = window.openDatabase('AddressBook', '1', 'Address Book', false, 
    function(db) {
      db.transaction(function(txn) {
          txn.createSequence('ContactSeq');
          txn.createEntityStore('Contact', 'id', 'ContactSeq');
          txn.changeVersion(database.version, '1');
        });
      });
      
database.transaction(function(txn) {
  //... some transaction processing
});

database = window.openDatabase('AddressBook', '2', 'Address Book', false,
    function(db) {
      db.transaction(function(txn) {
        var es = txn.getEntityStore('Contact');
        es.createIndex('ContactName', 'name', Index.MANY_TO_ONE);
        // database.version === '1'
        txn.changeVersion(database.version, '2');
      });
    });
  database.transaction(function(txn) {
    // ...
  });

interface Transaction {
    const unsigned short READ_UNCOMMITTED = 0;
    const unsigned short READ_COMMITTED = 1;
    const unsigned short SERIALIZABLE = 2;
    
    readonly attribute unsigned short isolationLevel;
    readonly attribute Transaction parent;
    
    void changeVersion(in DOMString oldVersion, 
                       in DOMString newVersion);  

    EntityStore getEntityStore(in DOMString name);
    EntityStore createEntityStore(in DOMString name, 
                                  in DOMString primaryKeyPath, 
                                  in optional DOMString sequenceName);

    Sequence getSequence(in DOMString name);
    Sequence createSequence(in DOMString name, 
                            in optional long long initial, 
                            in optional long long increment);
    
    Queue getQueue(in DOMString name);
    Queue createQueue(in DOMString name);                             
    

    abort();
    commit();
  };

3.4. Entity Store

An entity store is a persistent structure that holds key-value pairs sorted by keys so as to enable fast insertion and look up as well as ordered retrieval. The store provides a mechanism by which to read and write stored objects. Operations on an entity store must follow the transaction used to create or obtain the entity store.

Each EntityStore object provides access to a set of key/value pairs, which are sometimes called items. Values can be any data type supported by the structured clone algorithm [HTML5]. Keys themselves can be of any data type supported by the structured clone algorithm. They can be extracted from objects being stored or generated from a monotonic sequence.

var lincoln = {id: 1, name: 'Lincoln', number: '7012'};

var database = window.openDatabase('AddressBook', '1', 'Address Book', null, 
  function(Transaction txn) {
    txn.createEntityStore('Contact', 'id');
  });
database.transaction(function(Transaction txn) {
  var store = txn.getEntityStore('Contact');
  var lincolnID = store.put(lincoln);  
  // 1 === lincolnID
});

database = window.openDatabase('AddressBook', '1', 'Address Book', true);
database.transaction(function(Transaction txn) {
  var store = txn.getEntityStore('Contact');
  var lincolnContact = store.get(1);
  // lincolnContact.id === 1 && lincolnContact.name === 'Lincoln';
});

An entity store does not allow multiple items to be stored with the same primary. key If the same key is used to store a different item, then it will replace the object currently stored with the same key.

var abraham = {id: 1, name: 'Abraham', number: '2107'};

database.transaction(function(Transaction txn) {
  var store = txn.getEntityStore('Contact');
  var abrahamID = store.put(abraham);
  // 1 === abrahamID
});

database.transaction(function(Transaction txn) {
  var store = txn.getEntityStore('Contact');
  var abrahamContact = store.get(1);
  // abrahamContact.id === 1 && abrahamContact.name === 'Abraham';
});

If an application does not generate its own keys, it can use keys generated by a Sequence object.

var lincoln = {name: 'Lincoln', number: '7012'};

var database = window.openDatabase('AddressBook', '1', 'Address Book', null, 
  function(Transaction txn) {
    txn.createSequence('ContactSeq');
    txn.createEntityStore('Contact', 'id', 'ContactSeq');
  });
var lincolnID = null;
database.transaction(function(Transaction txn) {
  var store = txn.getEntityStore('Contact');
  lincolnID = store.put(lincoln);  
  // lincoln["id"] === lincolnID
});

database = window.openDatabase('AddressBook', '1', 'Address Book', true);
database.transaction(function(Transaction txn) {
  var store = txn.getEntityStore('Contact');
  var lincolnContact = store.get(lincolnID);
  // lincolnID == lincolnContact["id"] && lincolnContact["name"] == 'Lincoln';
});

An entity store arranges stored objects by their key, also referred to as the primary key. Each object contains the value of its primary key. Additionally, entity stores may also have one or more secondary keys declared for stored objects. Indices store data about secondary keys and refer to a primary key somewhere in the entity store.

var lincoln = {name: 'Lincoln', number: '7012'};
var abraham = {name: 'Abraham', number: '2107'};

var database = window.openDatabase('AddressBook', '1', 'Address Book', null, 
  function(Transaction txn) {
    txn.createSequence('ContactSeq');
    var store = txn.createEntityStore('Contact', 'id', 'ContactSeq');
    store.createIndex('ContactName', 'name', Index.MANY_TO_ONE);
  });
  
database.transaction(function(Transaction txn) {
  var store = txn.getEntityStore('Contact');
  store.put(lincoln);  
  store.put(abraham);
});

database = window.openDatabase('AddressBook', '1', 'Address Book', true);
database.transaction(function(Transaction txn) {
  var store = txn.getEntityStore('Contact');
  var allCursor = store.entities();
  var lCursor = store.getIndex('ContactName').entities('L');
  var l1 = lCursor.next();
  l1 = lCursor.next();
  var l2 = allCursor.next();
  // l1["id"] === l2["id"]
});

interface EntityStore {  
  readonly attribute DOMString name;
  readonly attribute DOMString keyPath;
  readonly DOMStringList indexNames;
  
  any put(in any object);
  delete(in any key);
  any get(in any key);
  
  Index getIndex(in DOMString name);
  Index createIndex(in DOMString name, 
                    in DOMString keyPath, 
                    in unsigned short cardinality, 
                    in optional unsigned short onRelatedEntityDelete, 
                    in optional DOMString relatedEntity);  

  remove();
  Cursor entities(in optional any from, 
                  in optional bool inclusive, 
                  in optional any to, 
                  in optional bool inclusive, 
                  in optional unsigned short isolationLevel);
  EntityJoin join();
};

On getting, name will provide the name of the entity store.

On getting, keyPath will provide the path of the key used as the primary key of objects stored in this entity store. This path can be the empty string if the object value is used as the key.

On getting, indexNames will provide a list of the names of indexes on objects in this entity store.

The put() method is used to store the given object in the entity store. Insert the object by performing the insertion steps.

The get() method is used to retrieve the object associated with the given key in the entity store. The following steps must be run for retrieving the object with the following parameters: key.

1. If key is not defined or null, then throw a newly constructed DatabaseException exception (Error code 3) and terminate these steps.
2. Use the key to look up an object in the entity store. Let value be that object.
3. If object is not found in the entity store, then throw a newly constructed DatabaseException exception (Error code 3) and terminate these steps.

The delete() method is used to delete the object associated with the given key in the entity store. Delete the object by performing the deletion steps.

The getIndex() method is used to obtain an Index object representing the named index on this entity store.

If an index with the given name, compared in a case-sensitive manner, does not already exist, then this method will throw a newly constructed DatabaseException exception (Error code 3).

The createIndex() method is used to define a new index on this entity store. An index is created using three required parameters - name, key path, and cardinality - and two optional parameters - action to be performed when related entity is deleted, and the name of the related entity.

If an index with the given name, compared in a case-sensitive manner, already exists, then this method will throw a newly constructed DatabaseException exception (Error code 4).

The remove() method is used to destroy the entity store as well as all associated indices.

The entities() method is used to access objects of an entity store. This method produces a Cursor object that is used to iterate over objects arranged by their keys. The parameters of this method are used to limit the range of primary keys over which the Cursor can be iterated. If an isolation level is provided, then it overrides the isolation level of the transaction used to obtain this entity store, and objects are accessed from the cursor with that level of isolation.

If there are two or more secondary indexes set for an entity store, then sets of objects can be retrieved from it based on the intersection of multiple index values using an EntityJoin object. The join() method is used to obtain such an object.

3.5. Index

Usually database objects are retrieved by means of the object's key. However, the key used for an object will not always contain the information required to provide rapid access to the data that may be needed.

An index can indicate a relationship of objects in one entity store to those in another. A relation has three attributes - the two entities that are related and a cardinality.

var contacts = [
  {id: 1, name: 'John', email: 'john@him.com'},
  {id: 2, name: 'Jane', email: 'jane@her.com'},
  {id: 3, name: 'Dan', email: 'dan@him.com'},
  {id: 4, name: 'Kim', email: 'kim@her.com'},              
];

var accounts = [
  {acct: 'x1', owner: 1, type: 'checking'},
  {acct: 'x3', owner: 2, type: 'saving'},
  {acct: 'y1', owner: 1, type: 'brokerage'},
  {acct: 'z4', owner: 4, type: 'saving'}
 ];

When an Index object relates two entity stores, it is important to consider the consequence of the deletion of an object on the related objects. If this is the case, foreign key constraints can be used to control data integrity.

When a foreign key constraint is declared:

1. a new secondary key for the object is stored, it is checked to make sure it exists as a primary key for the related entity object. If it does not, then a newly constructed DatabaseException exception (Error code 4) is thrown.
2. When a related entity is deleted, some action is automatically taken for the entities that refer to this object. The exact action can be one of the following:

   1. Nullify

      The referencing object can be modified to change its referring property to null.

   2. Cascade

      The referencing object can be deleted.

   3. Abort

      The delete action can be aborted so that no dangling references are left.

interface Index {
  const unsigned short ONE_TO_ONE = 0;
  const unsigned short MANY_TO_ONE = 1;
  const unsigned short ONE_TO_MANY = 2;
  const unsigned short MANY_TO_MANY = 3;

  const unsigned short NULLIFY = 0;
  const unsigned short CASCADE = 1;
  const unsigned short ABORT = 2;

  readonly attribute DOMString name;
  readonly attribute DOMString keyPath;
  readonly attribute unsigned short cardinality;
  readonly attribute unsigned short onRelatedEntityDelete; 
  readonly attribute DOMString relatedEntity;
  
  Cursor entities(in optional any from, 
                  in optional bool inclusive, 
                  in optional any to, 
                  in optional bool inclusive, 
                  in optional unsigned short isolationLevel);
  delete(in any key);

  remove();
};

The ONE_TO_ONE cardinality option indicates that the secondary key is unique to the object. If an object is stored with a secondary key that already exists in the entity store.

The MANY_TO_ONE cardinality option indicates the secondary key may be used for multiple objects in the entity store. That is, the key appears more than once, but for each stored object it can be used only once.

The ONE_TO_MANY cardinality option indicates that the secondary key might be used more than once for a given object. Secondary keys themselves are assumed to be unique, but multiple instances of the secondary key can be used per object.

The MANY_TO_MANY cardinality option indicates there can be multiple keys for any given object, and for any given key there can be many related objects.

The NULLIFY foreign constraint action option indicates that all entities related to the deleted entity are updated so that the pertinent property in objects is nullified.

The CASCADE cardinality option indicates that the secondary key might be used more than once for a given object. Secondary keys themselves are assumed to be unique, but multiple instances of the secondary key can be used per object.

The ABORT foreign constraint action indicates that the delete operation is not allowed. This is the default behavior.

On getting, name will provide the name of the index.

On getting, keyPath will provide the path of the key used as the secondary key of objects stored in this index. This path can be the empty string if the object value is used as the key.

On getting, cardinality will describe whether duplicate objects can be found in the index for a given secondary key. If the cardinality is ONE_TO_ONE or ONE_TO_MANY, duplicates will not occur. For the other cardinality levels, duplicates may occur.

On getting, onRelatedEntityDelete identifies the foreign key constraint action to take when the related entity is deleted.

On getting, relatedEntity identifies the name of the entity store that holds the related foreign entity for enforcing foreign key constraints.

The entities() method is used to access objects of an entity store as arranged in the index. This method produces a Cursor object that is used to iterate over objects arranged by their secondary keys. The parameters of this method are used to limit the range of secondary keys over which the Cursor can be iterated. If an isolation level is provided, then it overrides the isolation level of the transaction used to obtain this entity store, and objects are accessed from the cursor with that level of isolation.

The delete() method is used to delete the object associated with the given secondary key in the entity store. by looking up the primary keys for the given secondary key and performing the deletion steps for each of the primary keys.

The remove() method is used to destroy the index. None of the objects stored in the entity store are affected.

3.6. Cursor

Cursors provide a mechanism by which to iterate over the records in a database. Cursors can be used to get, put, and delete database records. If a database allows duplicate records, then cursors are the only mechanism by which to access anything other than the first duplicate for a given key.

When a cursor is obtained from an index or an entity store, it is not positioned to any value. Before accessing data from a cursor, it is necessary to position the cursor to a particular object in the cursor's range. The cursor can be initialized any methods that move the cursor. If data is accessed from an uninitialized cursor, then it will cause a newly constructed DatabaseException exception (Error code 1) to be thrown.

interface Cursor {
  any first();
  any last();
  any next();
  any previous();
  any nextDup();
  any nextNoDup();
  any prevNoDup();
  any prevDup();
  
  // these methods do not move the cursor
  unsigned long long count();          
  any current();
  boolean update(any object);
  delete();
};

The count method returns the total number of objects that share the current key.

The first() method is used to position the cursor to the first unique key in the cursor's range.

The last() method is used to position the cursor to the last unique key in the cursor's range.

The next() method is used to position the cursor to the next key in the cursor's range. If the cursor is uninitialized, its position is set to the first key. In the presence of duplicate key values, the value of the key may not change.

The previous() method is used to position the cursor to the next key in the cursor's range. If the cursor is uninitialized, its position is set to the last unique key. In the presence of duplicate key values, the value of the key may not change.

The nextDup() method is used to position the cursor to the next duplicate object for the current key. If no such object exists, this method returns null.

The prevDup() method is used to position the cursor to the previous duplicate object for the current key. If no such object exists, this method returns null.

The nextNoDup() method is used to position the cursor to the next unique key. If no such object exists, this method returns null. If the cursor is uninitialized, its position is set to the first key.

The prevNoDup() method is used to position the cursor to the previous unique key. If no such object exists, this method returns null. If the cursor is uninitialized, its position is set to the last key.

The update() method is used to update the object in the entity store at which the cursor is currently positioned. If the object is updated, then this method returns true. The update method is only allowed if the Cursor is obtained from an entity store.

The delete() method is used to delete the object in the entity store at which the cursor is currently positioned. The cursor can be moved to the next (or the previous) position after deleting an object. If a cursor is positioned on a deleted entity, current() will return null, delete() will return false, and update() will return false.

The current() method is used to obtain the object at the current cursor position.

3.7. Entity Join

interface EntityJoin {
  addCondition(in Index index, 
               in optional any key);
  Cursor entities(in optional unsigned short isolationLevel);
};

The addCondition() method is used to add an index condition to the join operation. If the parameter index is already added to this join operation, then a newly constructed DatabaseException exception (Error code 1) is thrown. If the parameter index is not on the same entity store as the entity join itself, then also, a newly constructed DatabaseException exception (Error code 1) is thrown. The parameter key is used to set a starting point in the index.

The entities() is used to obtain a cursor positioned to the object in the entity store that satisfies all the conditions specified in the join. If an isolation level is specified, it overrides the level specified in the transaction.

3.8. Sequence

Sequences provide an arbitrary number of persistent objects that return an increasing or decreasing sequence of integers. Implementations may cache blocks of values for a sequence to reduce contention. It is not necessary that the implementation provide consecutive values as long as it maintains the monotonically increasing or decreasing sequence of values. It is necessary that values be spaced at least as far apart as the increment value used at the time of creating the sequence.

interface Sequence {
  readonly attribute DOMString name;
  readonly attribute long long current;
  
  changeIncrement(long long increment);
  long long next();
  remove();
};

On getting, name will provide the name of the sequence.

On getting, current will provide the present value of the sequence. Unless a value is provided, the initial value of a sequence will be 1.

The changeIncrement() method is used to alter the amount by which the sequence is incremented (or decremented) each time the next() method is called.

The next() method is used to advance the sequence and obtain the next number in the sequence as calculated from its current value and increment. Unless a value is provided, the sequence will increment its value by 1.

The remove() method is used to destroy the sequence.

3.9. Queue

A queue is a simple first-in-first-out store that can hold data sorted by their arrival so as to enable fast insertion and sequential retrieval. Unlike entity stores, queues do not provide externally visible key-based retrieval of values. Nor is it possible to store items with an application specified key.

interface Queue {  
  readonly attribute DOMString name;

  push(in any object);
  any pop();
  
  remove();
};

On getting, name will provide the name of the queue.

The push() method is used to store the given object at the head of the queue.

The pop() method is used to delete the object that is at the head of the queue as ordered by their insertion in to the queue. The deleted object is also returned as result.

The remove() method is used to destroy the queue.

3.10. Exceptions and Errors

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

interface DatabaseError {
  const unsigned short UNKNOWN_ERR = 0;
  const unsigned short NON_TRANSIENT_ERR = 1; 
  const unsigned short VERSION_ERR = 2; 
  const unsigned short NOT_FOUND_ERR = 3;
  const unsigned short CONSTRAINT_ERR = 4;
  const unsigned short DATA_ERR = 5;
  const unsigned short FEATURE_ERR = 6;
  const unsigned short SERIAL_ERR = 11;
  const unsigned short TOO_LARGE_ERR = 12;
  const unsigned short RECOVERABLE_ERR = 21;
  const unsigned shrot TRANSIENT_ERR = 31;
  const unsigned short TIMEOUT_ERR = 32;
  unsigned short code;
  int status;
  DOMString message;
};

exception DatabaseException {
  const unsigned short UNKNOWN_ERR = 0;
  const unsigned short NON_TRANSIENT_ERR = 1; 
  const unsigned short VERSION_ERR = 2; 
  const unsigned short NOT_FOUND_ERR = 3;
  const unsigned short CONSTRAINT_ERR = 4;
  const unsigned short DATA_ERR = 5;
  const unsigned short FEATURE_ERR = 6;
  const unsigned short SERIAL_ERR = 11;
  const unsigned short TOO_LARGE_ERR = 12;
  const unsigned short RECOVERABLE_ERR = 21;
  const unsigned shrot TRANSIENT_ERR = 31;
  const unsigned short TIMEOUT_ERR = 32;
  unsigned short code;
  int status;
  DOMString message;
};

A.1. Normative references

[HTML5]

HTML5: A vocabulary and associated APIs for HTML and XHTML, Ian Hickson, editor, W3C Working Draft, August 2009.

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997.

[WebIDL]

Web IDL, Cameron McCormack, editor. W3C Working Draft, December 2008.

[WebStorage]

Web Storage, Ian Hickson, editor. W3C Working Draft, September 2009.

[WebWorkers]

Web Workers, Ian Hickson, editor. W3C Working Draft, April 2009.