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.
The asynchronous API methods return without blocking the calling thread.
All asynchronous operations immediately return an IDBRequest instance.
This object does not initially contain any information about the result of the operation.
Once information becomes available, an event is fired on the request and the information becomes
available through the properties of the IDBRequest instance.
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]].
In the following example, we open a database asynchronously. Various event handlers are registered for responding to various situations.
undefined when the request resulted
in an error. When the done flag is
false, getting this property MUST throw a DOMException of type InvalidStateError.
DOMException of type InvalidStateError.
null when there is no source set.
"pending", otherwise returns
"done".
When a request is made, a new request is returned with its
readyState set to
"pending".
If a request completes successfully, the
readyState
is changed to "done", the
result
is set to the result of the request, and an event with type success is fired
at the request.
If an error occurs while performing the operation, the
readyState
is changed to "done", the
error attribute is set to a DOMError type that matches the error,
and an event with type error is fired at the request.
The open and deleteDatabase functions on IDBFactory
uses a separate interface for its requests in order to make use of the
blocked event and upgradeneeded event easier.
blocked eventupgradeneeded eventThe task source for these tasks is the database access task source.
This specification fires events with the following custom interfaces:
"versionchange" transaction.Events are constructed as defined in Constructing events, in [[!DOM4]].
Window and
WorkerUtils objects
MUST implement the IDBEnvironment interface.
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.
When invoked, this method MUST create a request and return it. The created
request MUST implement the IDBOpenDBRequest interface and have its
source set to null.
The method then queues up an operation to run the steps for opening a database.
Let origin be the origin of the IDBEnvironment used to access
this IDBFactory, name and version be the name
and version parameters passed to this function, and request be
the newly created request.
If no version is specified and a database exists, use the current database version and follow the steps for opening a database. If no version is specified and no database exists, set database version to 1, follow the steps for opening a database, and return a database without object stores.
If an error is returned from the steps above, the implementation MUST set the
error attribute of the request
to a DOMError whose name is the same as the error returned,
and dispatch an event at the request.
The event must use the Event interface and have its type set
to "error". The event does bubble but is not cancelable. The propagation
path of the event is just the request.
If the steps above are successful, the implementation MUST set the
result to the connection created by the steps above and dispatch an event at request.
The event must use the Event interface and have its type set
to "success". The event does not bubble and is not cancelable. The propagation
path of the event is just the request. If the steps above resulted in a "versionchange" transaction being
run, then firing the "success" event MUST be done after the “versionchange” transaction completes.
The last requirement is to ensure that in case another version upgrade is about to happen,
the success event is fired on the connection first so that the page gets a chance to register
a listener for the versionchange event.
The firing of "success" or "error" events do not follow the normal
steps to fire a success event or fire an error event as there is no active
transaction at the time when they fire.
version is 0 (zero) or a negative number.When invoked, this method MUST create a request and return it. The created request must implement the IDBOpenDBRequest interface and have its source set to null. The method then queues up an operation to run the steps for deleting a database. Let origin be the origin of the IDBEnvironment used to access this IDBFactory and name be the name parameter passed to this function.
If an error is returned from the steps above, the implementation MUST set the
error attribute of the request
to a DOMError whose name is the same as the error returned,
and dispatch an event at the request.
The event must use the Event interface and have its type set
to "error". The event does bubble but is not cancelable. The propagation
path of the event is just the request.
If the steps above are successful, the implementation MUST set the
result of the request
to undefined and fire a success event at
the request.
The event MUST implement the IDBVersionChangeEvent interface and have oldVersion set to database version
and have the newVersion property set to null.
The firing of "success" or "error" events do not follow the normal
steps to fire a success event or fire an error event as there is no active
transaction at the time when they fire.
When invoked, this method MUST compare two keys. The method returns 1 if the first key is greater than the second, -1 if the first is less than the second, and 0 if the first is equal to the second.
A database object can be used to manipulate the objects of that database. It is also the only way to obtain a transaction for that database.
"versionchange"
transaction if createObjectStore
or deleteObjectStore
is called on this IDBDatabase instance itself.
This method creates and returns a new object store with the given name in the
connected database. If this function is called from
outside a "versionchange" transaction callback, or if this
function is called on a IDBDatabase object other than that transaction's
connection, the implementation MUST throw a
DOMException of type InvalidStateError.
If an objectStore with the same name already
exists, the implementation MUST throw a DOMException of type ConstraintError.
Otherwise, the implementation MUST create a new object store and return an IDBObjectStore object representing it.
This method synchronously modifies the IDBDatabase.objectStoreNames property. However it only changes the IDBDatabase.objectStoreNames property on the IDBDatabase instance on which it was called.
If the optionalParameters argument is specified and has a keyPath property
which is not undefined or null, then set keyPath to the value
of this property. If keyPath is an Array, then each item in the array is
converted to a string. If keyPath is not an Array, it is converted to a
string.
If keyPath is not a valid key path then a DOMException of type SyntaxError MUST be
thrown. Otherwise set the created object store's key path to the value of
keyPath.
If the optionalParameters parameter is specified, and autoIncrement is set to true, and
the keyPath parameter is specified to the empty string, or specified to an Array,
this function MUST throw a InvalidAccessError exception.
In some implementations it's possible for the implementation to run into problems
after queuing up an operation to create the object store after the createObjectStore function has returned.
For example in implementations where metadata about the newly created objectStore is inserted into the database asynchronously,
or where the implementation might need to ask the user for permission for quota reasons.
Such implementations MUST still create and return an IDBObjectStore object. Instead,
once the implementation realizes that creating the objectStore has failed, it MUST abort the transaction
using the steps for aborting a transaction using the appropriate error as error parameter. For example if
creating the object store failed due to quota reasons, QuotaError MUST be used as error.
keyPath specifies the key path of the new
object store. If the attribute is null,
no key path is
specified and thus keys are out-of-line.
autoIncrement specifies whether the object store
created should have a key generator."versionchange"
transaction callback. Also occurs if a request is made on a source object that has been deleted or removed.Array containing the empty string.
This method destroys the object store with the given name in the
connected database. If this function is called from
outside a "versionchange" transaction callback, or if this
function is called on a IDBDatabase object other than that transactions
connection, the implementation MUST throw a
DOMException of type InvalidStateError.
This method synchronously modifies the IDBDatabase.objectStoreNames property. However it only changes the IDBDatabase.objectStoreNames property on the IDBDatabase instance on which it was called.
"versionchange" transaction callback.
Also occurs if a request is made on a source object that has been deleted or removed.
This method, when called MUST execute the
steps for creating a transaction in an asychronous
fashion. The storeNames and mode arguments are
forwarded to the algorithm as-is. The callback argument is set to null.
The timeout argument is set to infinite.
The connection argument is set to the IDBDatabase that the
transaction() method was called on.
The method returns an IDBTransaction object representing the transaction returned by the steps above.
If this method is called on IDBDatabase object for which a "versionchange"
transaction is still running, a InvalidStateError exception MUST be thrown. I.e. if a
"versionchange" transaction is started when a database is opened and this method is
called on the IDBDatabase instance for that transaction before the transaction is committed,
a InvalidStateError exception MUST be thrown. Likewise, if this method is called on a
IDBDatabase instance where the closePending flag is set, a InvalidStateError
exception MUST be thrown.
"readonly".DOMString,
an Array of DOMStrings or null.
This method throws a DOMException of type ReadOnlyError if the transaction which this IDBObjectStore belongs to is
has its mode set to "readonly". If any of the following conditions are true, this method
throws a DOMException of type DataError:
Otherwise this method creates a structured clone of the value parameter. If the structured clone algorithm throws an exception, that exception is rethrown. Otherwise, run the steps for asynchronously executing a request and return the IDBRequest created by these steps. The steps are run with this IDBObjectStore as source and the steps for storing a record into an object store as operation, using this IDBObjectStore as store, the created clone as value, the key parameter as key, and with the no-overwrite flag flag set to false.
"readonly".
This method throws a DOMException of type ReadOnlyError if the transaction which this IDBObjectStore belongs to is
has its mode set to "readonly". If any of the following conditions are true, this method
throws a DOMException of type DataError:
Otherwise this method creates a structured clone of the value parameter. If the structure clone algorithm throws an exception, that exception is rethrown. Otherwise, run the steps for asynchronously executing a request and return the IDBRequest created by these steps. The steps are run with this IDBObjectStore as source and the steps for storing a record into an object store as operation, using this IDBObjectStore as store, the created clone as value, the key parameter as key, and with the no-overwrite flag flag set to true.
To determine if a transaction has completed successfully,
listen to the transaction’s complete event rather than the IDBObjectStore.add request’s success event,
because the transaction may still fail after the success event fires.
"readonly".
This method throws a ReadOnlyError if the transaction which this IDBObjectStore belongs to is
has its mode set to "readonly". If the key parameter is not a valid key
or a key range this method throws a DOMException of type DataError.
Otherwise this method runs the steps for asynchronously executing a request and returns the IDBRequest created by these steps. The steps are run with this IDBObjectStore as source and the steps for deleting records from an object store as operation, using this IDBObjectStore as store and the key parameter as key.
Unlike other methods which take keys or key ranges, this method does not allow null to be passed as key. This is to reduce the risk that a small bug would clear a whole object store.
"readonly".
If the key parameter is not a valid key or a key range, this method
throws a DOMException of type DataError. Otherwise, this method runs the steps for asynchronously executing
a request and returns the IDBRequest created by these steps. The steps are run with this
IDBObjectStore as source and the steps for retrieving a value from an
object store as operation, using this IDBObjectStore as store and the
key parameter as key.
This function produces the same result if a record with the given key doesn't exist as when a record
exists, but has undefined as value. If you need to tell the two situations apart, you can use
openCursor with the same key. This will return a cursor with
undefined as value if a record exists, or no cursor if no such record exists.
This method throws a DOMException of type ReadOnlyError if the transaction which this IDBObjectStore belongs to is
has its mode set to "readonly".
Otherwise this method runs the steps for asynchronously executing a request and returns the IDBRequest created by these steps. The steps are run with this IDBObjectStore as source and the steps for clearing an object store as operation, using this IDBObjectStore as store.
"readonly".
If the range parameter is specified but is not a valid key or a key range,
this method throws a DOMException of type DataError. Otherwise, this method creates a cursor. The cursor
MUST implement the IDBCursorWithValue interface.
The newly created cursor MUST have an undefined position, a direction set to the value of the direction parameter, false as iterable flag value, and undefined key and value. The source of the cursor is the IDBObjectStore this function was called on.
If the range parameter is a key range then the cursor's range MUST be set to that range. Otherwise, if the range parameter is a valid key then the cursor's range is set to key range containing only that key value. If the range parameter is not specified, the cursor's key range is left as undefined.
This method runs the steps for asynchronously executing a request and returns the IDBRequest created by these steps. The steps are run with this IDBObjectStore as source and the steps for iterating a cursor as operation, using the created cursor as cursor and with undefined as key.
This method creates and returns a new index with the given name and parameters in the
connected database. If this function is called from
outside a "versionchange" transaction callback, the implementation
MUST throw an DOMException of type InvalidStateError exception.
If an index with the same name already exists, the implementation MUST throw a DOMException of type ConstraintError.
Otherwise, the implementation MUST create a new index and return an IDBIndex object representing it. The created
index has its unique and multiEntry flags are set to the values of the
unique and multiEntry properties in the optionalParameters argument.
If the keyPath argument is an Array, then each item in the array is
converted to a DOMString. If keyPath is not an Array, it is converted to a
DOMString.
If keyPath is not a valid key path then a DOMException of type SyntaxError MUST be
thrown. Otherwise set the created object store's key path to the value of
keyPath. If keyPath is
an Array and the multiEntry property in the optionalParameters is true,
then a DOMException of type InvalidAccessError MUST be thrown. Otherwise set the created index's
key path to the value of keyPath.
The index that is requested to be created can contain constraints on the data allowed in the index's
referenced object store, such as requiring uniqueness of the values referenced by the
index's keyPath. If the referenced object store already contains data which violates these
constraints, this MUST NOT cause the implementation of createIndex to throw an exception or affect what it returns.
The implementation MUST still create and return an IDBIndex object.
Instead the implementation must queue up an operation to abort the "versionchange" transaction
which was used for the createIndex call.
This method will synchronously modify the IDBObjectStore.indexNames property.
In some implementations it's possible for the implementation to asynchronously run into problems
creating the index after the createIndex function has returned.
For example in implementations where metadata about the newly created index is
queued up to be inserted into the database asynchronously,
or where the implementation might need to ask the user for permission for quota reasons.
Such implementations MUST still create and return an IDBIndex object. Instead,
once the implementation realizes that creating the index has failed, it MUST abort the transaction
using the steps for aborting a transaction using the appropriate error as error parameter. For example if
creating the index failed due to quota reasons, QuotaError MUST be used as error and if the index
can't be created due to unique constraints, ConstraintError MUST be used as error.
unique specifies whether the index's unique flag is
set.
multiEntry specifies whether the index's multiEntry flag is
set.
"versionchange"
transaction callback. Also occurs if a request is made on a source object that has been deleted or removed.
This method destroys the index with the given name in the
connected database. Note that this
method must only be called from a "versionchange"
transaction callback.
This method will synchronously modify the IDBObjectStore.indexNames property.
"versionchange"
transaction callback.
If the optional key parameter is not a valid key or a key range,
this method throws a DOMException of type DataError.
This method runs the steps for asynchronously executing a request and returns the IDBRequest created by these steps.
The steps are run with this IDBObjectStore as source and the steps for iterating a cursor as operation,
using the created cursor as cursor.
If provided, use the key parameter as key, otherwise, use undefined as key.
If the result of the algorithm is null return 0 (zero) as the result for the request.
Otherwise, use the return cursor to determine the total number of objects that share the
key or key range and return that value as the result for the request.
IDBKeyRange.
Index objects implement the following interface:
DOMString or
an Array of DOMStrings.
If the range parameter is specified but is not a valid key or a key range,
this method throws a DOMException of type DataError.
Otherwise, this method creates a cursor.
The cursor MUST implement the IDBCursorWithValue interface.
The newly created cursor MUST have an undefined position, a direction set to the value of the direction parameter, false as iterable flag value, and undefined key and value. The source of the cursor is the IDBIndex this function was called on.
If the range parameter is a key range then the cursor's range is set to that range. Otherwise, if the range parameter is a valid key then the cursor's range is set to key range containing only that key value. If the range parameter is not specified, the cursor's key range is left as undefined.
This method runs the steps for asynchronously executing a request and returns the IDBRequest created by these steps. The steps are run with this IDBIndex as source and the steps for iterating a cursor as operation, using the created cursor as cursor and with undefined as key
If the range parameter is specified but is not a valid key or a key range,
this method throws a DOMException of type DataError. Otherwise, this method creates a cursor. The cursor
MUST implement the IDBCursor interface, but MUST NOT implement the IDBCursorWithValue interface.
The newly created cursor MUST have an undefined position, a direction set to the value of the direction parameter, false as iterable flag value, and undefined key and value. The source of the cursor is the IDBIndex this function was called on.
If the range parameter is a key range then the cursor's range is set to that range. Otherwise, if the range parameter is a valid key then the cursor's range is set to key range containing only that key value. If the range parameter is not specified, the cursor's key range is left as undefined.
This method runs the steps for asynchronously executing a request and returns the IDBRequest created by these steps. The steps are run with this IDBObjectStore as source and the steps for iterating a cursor as operation, using the created cursor as cursor and with undefined as key
If the key parameter is not a valid key or a key range, this method
throws a DOMException of type DataError. This method runs the steps for asynchronously executing a request
and returns the IDBRequest created by these steps. The steps are run with this
IDBObjectStore as source and the steps for retrieving a referenced value from an
index as operation, using this IDBIndex as index and the
key parameter as key.
This function produces the same result if a record with the given key doesn't exist as when a record
exists, but has undefined as value. If you need to tell the two situations apart, you can use
openCursor with the same key. This will return a cursor with
undefined as value if a record exists, or no cursor if no such record exists.
Gets the primary key of the record from the referenced object store entry.
If the key parameter is not a valid key or a key range, this method
throws a DOMException of type DataError. This method runs the steps for asynchronously executing a request
and returns the IDBRequest created by these steps. The steps are run with this
IDBObjectStore as source and the steps for retrieving a value from an
index as operation, using this IDBIndex as index and the
key parameter as key.
If the optional key parameter is not a valid key or a key range,
this method throws a DOMException of type DataError.
This method runs the steps for asynchronously executing a request and returns the IDBRequest created by these steps.
The steps are run with this IDBIndex as source and the steps for iterating a cursor as operation,
using the created cursor as cursor.
If provided, use the key parameter as key, otherwise, use undefined as key.
If the result of the algorithm is null return 0 (zero) as the result for the request.
Otherwise, use the return cursor to determine the total number of objects that share the
key or key range and return that value as the result for the request.
IDBKeyRange.
Cursor objects implement the following interface:
Array), it returns the same
object instance every time it is inspected, until the cursor's key is changed.
This means that if the object is modified,
those modifications will be seen by anyone inspecting the value of the cursor. However modifying such an object
does not modify the contents of the database.Array), it returns the same
object instance every time it is inspected, until the cursor's effective key is changed.
This means that if the object is modified,
those modifications will be seen by anyone inspecting the value of the cursor. However modifying such an object
does not modify the contents of the database.
This method throws a DOMException of type ReadOnlyError if the transaction which this IDBCursor belongs to
has its mode set to "readonly". If this cursor's got value flag is false or if this
cursor was created using
openKeyCursor. This method
throws a DOMException of type InvalidStateError. If the effective object store of this cursor uses in-line
keys and evaluating the key path
of the value parameter results in a different value than the cursor's effective key,
this method throws a DOMException of type DataError.
Otherwise this method creates a structured clone of the value parameter. If the structured clone algorithm throws an exception, that exception is rethrown. Otherwise, run the steps for asynchronously executing a request and return the IDBRequest created by these steps. The steps are run with this IDBCursor as source and the steps for storing a record into an object store as operation, using this cursor's effective object store as store, the created clone as value, this cursor's effective key as key, and with the no-overwrite flag flag set to false.
A result of running the steps for storing a record into an object store is that if the record has been deleted since the cursor moved to it, a new record will be created.
"readonly"openKeyCursor or if the cursor
is currently being iterated or has iterated past the end.This method runs the steps for asynchronously executing a request. However, the steps are slightly modified such that instead of creating a new IDBRequest, it reuses the request originally created when this cursor was created. The done flag on the request is set to false before the request is returned. The steps are run with the cursor's source as source. The operation runs the steps for iterating a cursor count number of times with null as key and this cursor as cursor.
Before this method returns, unless an exception was thrown, it sets the got value flag on the cursor to false.
Calling this method more than once before new cursor data has been loaded is not allowed
and results in a DOMException of type InvalidStateError being thrown.
For example, calling advance() twice from the same onsuccess handler
results in a DOMException of type InvalidStateError being thrown on the second call.
If the value for count is 0 (zero) or a negative number, this method MUST
throw a JavaScript TypeError exception.
count parameter was zero or a negative number.
If this cursor's got value flag is false, this method throws a DOMException of type InvalidStateError.
If the key parameter is specified and fulfills any of these conditions this
method MUST throw a DOMException of type DataError:
Otherwise this method runs the steps for asynchronously executing a request. However, the steps are slightly modified such that instead of creating a new IDBRequest, it reuses the request originally created when this cursor was created. The done flag on the request is set to false before the request is returned. The steps are run with the cursor's source as source and the steps for iterating a cursor as operation, using this cursor as cursor and the key parameter as key.
Before this method returns, unless an exception was thrown, it sets the got value flag on the cursor to false.
Calling this method more than once before new cursor data has been loaded is not allowed
and results in a DOMException of type InvalidStateError being thrown.
For example, calling continue() twice from the same onsuccess handler
results in a DOMException of type InvalidStateError being thrown on the second call.
This method throws a DOMException of type ReadOnlyError if the transaction which this IDBCursor belongs to
has its mode set to "readonly". If this cursor's got value flag is false,
or if this cursor was created using
openKeyCursor a
DOMException of type InvalidStateError is thrown.
Otherwise this method runs the steps for asynchronously executing a request and returns the IDBRequest created by these steps. The steps are run with this IDBCursor as source and the steps for deleting records from an object store as operation, using this cursor's effective object store and effective key as store and key respectively.
"readonly".openKeyCursor or the cursor
is currently being iterated or has iterated past the end.Transaction objects implement the following interface:
abort function, this property
returns null.
If this transaction was aborted due to a failed request, this property returns the same
DOMError as the request which caused this transaction to be aborted.
If this transaction was aborted due to an error when committing the transaction, and not due to a failed
request, this property returns a DOMError which contains the reason for the transaction
failure (e.g. QuotaExceededError or UnknownError).
DOMException of type InvalidStateError.
Otherwise this method sets the transaction's active flag to false and
aborts the transaction by running the
steps for aborting a transaction with the error parameter set to null.
To determine if a transaction has completed successfully,
listen to the transaction’s complete event rather than the IDBObjectStore.add request’s success event,
because the transaction may still fail after the success event fires.