3.1 Constructs
3.1.1 Database
Each origin has an associated set of
databases. A database comprises
one or more object stores which hold the data stored
in the database.
Every database has a name which identifies it
within a specific origin. The name can be any string value, including the empty string, and
stays constant for the lifetime of the database. Each database also has a current
version. When a database is first created, its version is 0.
Implementations must support all names. If an implementation
uses a storage mechanism which can't handle arbitrary database names,
the implementation must use an escaping mechanism or something similar
to map the provided name to a name that it can handle.
Each database has one version at a time; a database
can't exist in multiple versions at once. The only way to change the version is using a "versionchange"
transaction.
Databases has a delete pending flag which is used during deletion. When a database is requested
to be deleted the flag is set to true and all attempts at opening the database are stalled until the database
can be deleted.
The act of opening a database creates a connection. There may be multiple
connections to a given database at any given time. Each connection has a
closePending flag which initially is set to false.
When a connection is initially created it is in opened state. The connection
can be closed through several means. If the connection is GCed
or execution context where the connection is created is destroyed (for example due to the
user navigating away from that page), the connection is closed. The connection can also be closed
explicitly using the steps for closing a database connection. When the connection is closed
the closePending flag is always set to true if it hasn't already been.
The IDBDatabase and IDBDatabaseSync
interfaces represent a connection to a database.
3.1.2 Object Store
An object store is the primary storage mechanism for storing data in a
database.
Each database contain a set of object stores. The set of object stores can be changed,
but can only be changed using a "versionchange" transactions, i.e. in response to a
upgradeneeded event. When a new database is created it doesn't contain any object stores.
The object store has a list of records which hold the
data stored in the object store. Each record consists of a key and a value.
The list is sorted according to key in ascending order. There can never be multiple records in a given object
store with the same key.
Every object store has a name.
The name is unique within the database to which it belongs. Every object store also optionally has a
key generator and an optional key path.
If the object store has a key path it is said to use in-line keys. Otherwise it is said to
use out-of-line keys.
The object store can derive the key from one of three sources:
-
A key generator. A key generator generates a monotonically increasing numbers every time
a key is needed.
-
Keys can be derived via a key path.
-
Keys can also be explicitly specified when a value is stored in the object store.
The IDBObjectStore and IDBObjectStoreSync
interfaces represent an object store. Note however that multiple instances of those
interfaces representing the same object store can exist.
3.1.3 Keys
In order to efficiently retrieve records stored in an indexed database,
each record is organized according to its key. A value is said to be a valid key
if it is one of the following types:
Array JavaScript objects [ECMA-262], DOMString [WEBIDL],
Date [ECMA-262] or float [WEBIDL].
However Arrays are only valid keys if every item in the array is defined and is
a valid key (i.e. sparse arrays can not be valid keys) and if the Array doesn't directly or
indirectly contain itself.
Any non-numeric properties are ignored, and thus does not affect whether the Array is a valid key.
Additionally, if the value is of type float, it is only a valid key if it is not NaN,
and if the value is of type Date it is only a valid key if its [[PrimitiveValue]]
internal property, as defined by [ECMA-262], is not NaN.
Conforming user agents must support all valid keys as keys.
Infinite float values are valid keys. As are empty Arrays.
For purposes of comparison, all Arrays are greater than all DOMString,
Date and float values; all DOMString values are greater than all
Date and float values; and all Date values are greater than all
float values. Values of type float are compared to other float values
numerically. Values of type Date are compared to other Date values chronologically.
Values of type DOMString are compared to other values of type DOMString
by using the algorithm defined by step 4 of section 11.8.5, The Abstract Relational Comparison Algorithm,
of the ECMAScript Language Specification [ECMA-262].
Values of type Array are compared to other values of type Array as follows:
-
Let A be the first
Array value and B be the second Array
value.
-
Let length be the lesser of A's length and B's length.
-
Let i be 0.
-
If the ith value of A is less than the ith value of
B, then A is less than B. Skip the remaining steps.
-
If the ith value of A is greater than the ith value of
B, then A is greater than B. Skip the remaining steps.
-
Increase i by 1.
-
If i is not equal to length, go back to step 4. Otherwise continue to next step.
-
If A's length is less than B's length, then A is less
than B. If A's length is greater than B's length, then
A is greater than B. Otherwise A and B are equal.
Note that Arrays that contain other Arrays are allowed as valid keys.
In this case the algorithm above runs recursively when comparing the individual values in the arrays.
As a result of the above rules, negative infinity is the lowest possible value for a key.
There is no highest possible key value.
This is because an array of any candidate highest key followed by another valid key is even higher.
The terms greater than, less than and equal to is defined in the terms of
the above comparisons.
The following examples illustrate the different behaviors when trying to use in-line keys and key generators
to save an object to an object store.
If the following conditions are true:
Then the value provided by the key generator is used to populate the key value.
In the example below the key path for the object store is "foo.bar".
The actual object has no value for the bar property, { foo: {} }.
When the object is saved in the object store the bar property is assigned a value of 4
because that is the next key generated by the object store.
If the following conditions are true:
Then the value associated with the key path property is used.
The auto-generated key is not used.
In the example below the keypath for the object store is "foo.bar".
The actual object has a value of 10 for the bar property, { foo: { bar: 10} }.
When the object is saved in the object store the bar property keeps its value of 10, because that is the key value.
ECMAScript
"foo.bar"
{ foo: { bar: 10 } }
The following example illustrates the scenario when the specified in-line key is defined through a key path but there is no property matching it.
The value provided by the key generator is then used to populate the key value and the system is responsible
for creating as many properties as it requires to suffice the property dependencies on the hierarchy chain.
In the example below the key path for the object store is "foo.bar.baz".
The actual object has no value for the foo property, { zip: {} }.
When the object is saved in the object store the foo, bar, and baz properties
are created each as a child of the other until a value for foo.bar.baz can be assigned.
The value for foo.bar.baz is the next key generated by the object store.
ECMAScript
"foo.bar.baz"
{ zip: {} }
Attempting to store a property on a primitive value will fail and throw an error.
In the first example below the key path for the object store is "foo".
The actual object is a primitive with the value, 4.
Trying to define a property on that primitive value fails.
The same is true for arrays. Properties are not allowed on an array.
In the second example below, the actual object is an array, [10].
Trying to define a property on the array fails.
ECMAScript
// The key generation will attempt to create and store the key path property on this primitive.
"foo"
4
// The key generation will attempt to create and store the key path property on this array.
"foo"
[10]
3.1.5 Key Path
A key path is a DOMString that defines how to extract a key from a value.
A valid key path is
either the empty string, a JavaScript identifier, or multiple Javascript identifiers separated by
periods (ASCII character code 46) [ECMA-262]. (Note that spaces are not allowed
within a key path.) To evaluate a key path, run the
steps for extracting a key from a value using a key path.
Key path values can only be accessed from properties explicitly copied by the structured clone algorithm,
as well as the following properties:
Blob.sizeBlob.typeFile.nameFile.lastModifiedDateArray.lengthString.length
3.1.6 Index
It is sometimes useful to retrieve records in an object store through other means
than their key. An index allows looking up records in an object store
using properties of the values in the object stores records.
An index is a specialized persistent key-value storage and has a referenced object store.
The index has a list of records which hold the
data stored in the index. The records in an index are automatically populated whenever records in the
referenced object store are inserted, updated or deleted. There can be several indexes
referencing the same object store, in which changes to the object store cause all such indexes
to get updated.
The values in the index's records are always values of keys in the index's referenced
object store. The keys are derived from the referenced object store's values using a key path.
If a given record with key X in the object store referenced by the index has the value A, and
evaluating the index's key path on A yields the result
Y, then the index will contain a record with key Y and value X.
Records in an index are said to have a referenced value. This is the value of the record in the index's referenced
object store which has a key equal to the index's record's value. So in the example above,
the record in the index whose key is Y and value is X has a referenced value of A.
Each record in an index reference one and only one record in the index's referenced
object store. However there can be
multiple records in an index which reference the same record
in the object store. And there can also be no records in an index
which reference a given record in an object store.
The records in an index are always sorted according to the records key. However unlike object stores,
a given index can contain multiple records with the same key. Such records are additionally sorted according to
the records value.
An index contains a unique flag. When this flag is set to true, the index enforces that no two records
in the index has the same key. If a record
in the index's referenced object store is attempted to be inserted or
modified such that evaluating the index's key path on the
records new value yields a result which already exists in the
index, then the attempted modification to the object store
fails.
An index also contains a multiEntry flag. This flag affects how the index behaves when the result of evaluating
the index's key path yields an Array. If the multiEntry flag is false, then
a single record whose key is an Array is added to the index. If the multiEntry flag is
true, then the one record is added to the index for each item in the Array. The key for each
record is the value of respective item in the Array.
The IDBIndex and IDBIndexSync interfaces
provide access to the metadata of an index. Note however that multiple instances of those
interfaces representing the same index can exist.
3.1.7 Transaction
A transaction is used to interact with the data in a database.
Whenever data is read or written to the database it is done by using a transaction.
All transactions are created through a connection, which is the transaction's
connection.
The transaction has a mode that determines which types of interactions can be performed
upon that transaction. The mode is set when the transaction is created and remains
fixed for the life of the transaction. The transaction also has a scope that
determines the object stores with which the transaction may interact. Transactions
have an active flag, which determines if new requests can be made
against the transaction. Finally, transactions also contain a request list of
requests which have been made against the transaction.
Each transaction has a fixed scope, determined when the transaction is created.
A transaction's scope remains fixed for the lifetime of that transaction.
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 data mutation operations.
Transactions are expected to be short lived. This is encouraged
by the automatic committing functionality described below. Authors can still cause
transactions to run for a long time; however, this usage pattern
is not generally recommended as it can lead to a bad user experience.
The lifetime of a transaction is as follows:
-
A transaction is created using
IDBDatabase.transaction.
The arguments passed determine the scope of the transaction and whether the transaction is read-only.
When a transaction is created its active flag is initially set to true.
-
The implementation must allow requests to be placed against the transaction
whenever the active flag is true. This is the case even if the transaction has not yet been
started. Until the transaction is started
the implementation must not execute these requests; however, the implementation must keep track of the
requests and their order. Requests may be placed against a transaction only while that transaction
is active. If an attempt is made to place a request against a transaction when that transaction is not
active, the implementation must reject the attempt by throwing a
DOMException of type TransactionInactiveError.
-
Once an implementation is able to enforce the constraints defined for the transaction mode, defined below,
the implementation must queue up an operation to start the transaction asynchronously.
The timing for when this happens is affected by:
- The mode in which the transaction is opened.
- Which object stores are included in the scope of the transaction.
-
Once the transaction has been started the implementation can
start executing the requests placed against the transaction. Unless otherwise defined, requests
must be executed in the order in which they were made against the transaction. Likewise, their results must
be returned in the order the requests were placed against a specific transaction.
There is no guarantee about the order that results from requests in different transactions are returned.
Similarly, the transaction modes ensure that two requests placed against different transactions
can execute in any order without affecting what resulting data is stored in the database.
-
A transaction can be aborted at any time before it is finished,
even if the transaction isn't currently active or hasn't yet started.
When a transaction is aborted the implementation must undo (roll back) any changes
that were made to the database during that transaction. This includes both changes to the contents of
object stores as well as additions and removals of object stores and indexes.
-
A transaction can fail for reasons not tied to a particular DOMRequest. For example due to IO errors
when committing the transaction, or due to running into a quota limit where the implementation can't tie
exceeding the quota to a partcular request. In this case the implementation must run the
steps for aborting a transaction using the transaction as transaction and the appropriate
error type as error. For example if quota was exceeded then
QuotaExceededError should
be used as error, and if an IO error happened, UnknownError should be used as
error.
-
When a transaction can no longer become active, the implementation must attempt to
commit it, as long as the transaction has not been aborted.
This usually happens after all requests placed against the
transaction have been executed and their returned results handled, and no new requests have been placed
against the transaction. When a transaction is committed, the implementation must atomically write
any changes to the database made by requests placed against the transaction. That is, either all
of the changes must be written, or if an error occurs, such as a disk write error, the implementation
must not write any of the changes to the database. If such an error occurs, the implementation must
abort the transaction by following the steps for aborting a transaction, otherwise it
must commit the transaction by following the steps for committing a transaction.
-
When a transaction is committed or aborted, it is said to be
finished. If a transaction can't be finished, for example
due to the implementation crashing or the user taking some explicit action to cancel it, the
implementation must abort the transaction.
Transactions are opened in one of three modes. The mode
determines how concurrent access to object stores in the transaction are isolated.
"readonly". This mode means that the transaction is only allowed
to read data. No modifications can be done by this type of transaction. This has the advantage
that several "readonly" transactions can run at the same time even if their scopes
are overlapping, i.e. if they are using the same object stores. This type of transaction can
be created any time once a database has been opened using the IDBDatabase.transaction() or
IDBDatabaseSync.transaction() functions."readwrite". The type of transaction is allowed to read, modify and
delete data from existing object stores. However object stores and indexes can't be added or removed.
Multiple "readwrite" transactions can't run at the same time if their scopes are overlapping
since that would mean that they can modify each other's data in the middle of the transaction.
This type of transaction can be created any time once a database has been opened using the
IDBDatabase.transaction() function."versionchange". This is similar to a "readwrite" transaction,
however it can additionally create and remove object stores and indexes. It's the only type of
transaction that can do so. This type of transaction can't be manually created, but instead is created
automatically when a upgradeneeded event is fired.
The this is defined in more detail below.
Any number of transactions opened in "readonly" mode are allowed to run concurrently,
even if the transaction's scope overlap and include the same object stores.
As long as a "readonly" transaction is running, the data that the implementation returns
through requests created with that transaction must remain
constant. That is, two requests to read the same piece of data must yield the same result
both for the case when data is found and the result is that data, and for the case when data
is not found and a lack of data is indicated.
There are a number of ways that an implementation ensures this. The implementation can prevent any
"readwrite" transaction, whose scope overlaps the scope of the "readonly" transaction, from
starting until the "readonly" transaction finishes. Or the implementation can allow the "readonly"
transaction to see a snapshot of the contents of the object stores which is taken when
the "readonly" transaction started.
Similarly, implementations must ensure that a "readwrite" transaction is only affected by
changes to object stores that are made using the transaction itself. For example, the
implementation must ensure that another transaction does not modify the contents of
object stores in the "readwrite" transaction's scope. The implementation
must also ensure that if the "readwrite" transaction completes successfully, the
changes written to object stores using the transaction can be committed to the
database without merge conflicts. An implementation must not abort a transaction
due to merge conflicts.
If multiple "readwrite" transactions are attempting to access the same object store (i.e.
if they have overlapping scope), the transaction that was
created first must be the transaction which gets access to the object store first. Due to
the requirements in the previous paragraph, this also means that it is the only transaction
which has access to the object store until the transaction is finished.
Generally speaking, the above requirements mean that "readwrite" transactions which have overlapping
scopes always run in the order they were created, and never run
in parallel.
A "versionchange" transaction never run concurrently with other transactions.
When a database is opened with a version number higher than the current version, a new
"versionchange" transaction is automatically created and made available through the
"upgradeneeded" event. The "upgradeneeded" event isn't fired, and thus the
"versionchange" transaction isn't started, until all other connections to the same
database are closed. This ensures that all other transactions are finished.
As long as a "versionchange" transaction
is running, attempts to open more connections to the same database are delayed,
and any attempts to use the same connection to start additional transactions will result in
an exception being thrown. Thus "versionchange" transactions not only ensure that
no other transactions are running concurrently, but also ensure that no other transactions are queued
against the same database as long as the transaction is running.
"versionchange" transaction is automatically created
when a database version number is provided that is greater than the current database version.
This transaction will be active inside the onupgradeneeded event handler,
allowing the creation of new object stores and indexes.
User agents must ensure a reasonable level of fairness across transactions to prevent
starvation. For example, if multiple "readonly" transactions are started one after another
the implementation must not indefinitely prevent a pending "readwrite"
transaction from starting.
Each transaction object implements either the IDBTransaction or the
IDBTransactionSync interface.
3.1.9 Key Range
Records can be retrieved from object stores and indexes
using either keys or key ranges. A
key range is a continuous interval over some data type
used for keys.
A key range may be lower-bounded or upper-bounded
(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 lower-bounded and upper-bounded.
If a key range is neither lower-bounded nor upper-bounded it is said to be unbounded.
A key range may be open (the key range does not include its endpoints)
or closed (the key range includes its endpoints).
A key range may consist of a single value.
The IDBKeyRange interface defines a
key range.
interface IDBKeyRange {
readonly attribute any lower;
readonly attribute any upper;
readonly attribute boolean lowerOpen;
readonly attribute boolean upperOpen;
static IDBKeyRange only (any value);
static IDBKeyRange lowerBound (any lower, optional boolean open);
static IDBKeyRange upperBound (any upper, optional boolean open);
static IDBKeyRange bound (any lower, any upper, optional boolean lowerOpen, optional boolean upperOpen);
};
Attributes
lower of type any, readonly- This value is the lower-bound of the key range.
No exceptions.
lowerOpen of type boolean, readonly- Returns false if the lower-bound value is included in the key range.
Returns true if the lower-bound value is excluded from the key range.
No exceptions.
upper of type any, readonly- This value is the upper-bound of the key range.
No exceptions.
upperOpen of type boolean, readonly- Returns false if the upper-bound value is included in the key range.
Returns true if the upper-bound value is excluded from the key range.
No exceptions.
Methods
bound-
Creates and returns a new key range with lower set to
lower, lowerOpen set to lowerOpen,
upper set to upper and
upperOpen set to upperOpen.
| Parameter | Type | Nullable | Optional | Description |
|---|
| lower | any | ✘ | ✘ | The lower-bound value |
| upper | any | ✘ | ✘ | The upper-bound value |
| lowerOpen | boolean | ✘ | ✔ | Set to false if the lower-bound should be included in the key range. Set to true if the lower-bound value should
be excluded from the key range. Defaults to false (lower-bound value is included). |
| upperOpen | boolean | ✘ | ✔ | Set to false if the upper-bound should be included in the key range. Set to true if the upper-bound value should
be excluded from the key range. Defaults to false (upper-bound value is included). |
| Exception | Description |
|---|
| DOMException | DataError | Either the lower or upper parameters were not passed a valid key
or the lower key is greater than the upper key or the lower key and upper key match and either
of the bounds are open. |
|
lowerBound-
Creates and returns a new key range with lower set to
lower, lowerOpen set to open,
upper set to
undefined and
and upperOpen set to true.
| Parameter | Type | Nullable | Optional | Description |
|---|
| lower | any | ✘ | ✘ | The lower bound value |
| open | boolean | ✘ | ✔ | Set to false if the lower-bound should be included in the key range. Set to true if the lower-bound value should
be excluded from the key range. Defaults to false (lower-bound value is included). |
only-
Creates and returns a new key range with both lower and
upper set to value and both
lowerOpen and upperOpen
set to false.
| Parameter | Type | Nullable | Optional | Description |
|---|
| value | any | ✘ | ✘ | The only value |
upperBound-
Creates and returns a new key range with lower set to
undefined, lowerOpen set to true,
upper set to upper and
and upperOpen set to open.
| Parameter | Type | Nullable | Optional | Description |
|---|
| upper | any | ✘ | ✘ | The upper bound value |
| open | boolean | ✘ | ✔ | Set to false if the upper-bound should be included in the key range. Set to true if the upper-bound value should
be excluded from the key range. Defaults to false (upper-bound value is included). |
A key is in a key range if both the following conditions are
fulfilled:
3.1.10 Cursor
Cursors are a transient mechanism used to
iterate over multiple records in a database.
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. The cursor has a source that indicates
which index or object store is associated with the records over which the cursor is iterating.
A cursor maintains a position over
this series, which moves in a direction that is in either
monotonically increasing or decreasing order of the record keys. Cursors
also have a key and a value
which represent the key and the value of the last iterated record.
Cursors finally have a got value flag. When this flag is false, the cursor is either
in the process of loading the next value or it has reached the end of its range, when it
is true, it indicates that the cursor is currently holding a value and that it is ready to iterate
to the next one.
There are four possible values for a cursor's direction. The direction of a cursor determines
if the cursor initial position is at the start of its source or at its end.
It also determines in which direction the cursor moves when iterated, and if it skips duplicated values
when iterating indexes. The allowed values for a cursor's direction is as follows:
"next". This direction causes the cursor to be opened at the start of the
source. When iterated, the cursor should yield all records, including
duplicates, in monotonically increasing order of keys."nextunique". This direction causes the cursor to be opened at the start of the
source. When iterated, the cursor should not yield records with
the same key, but otherwise yield all records, in monotonically increasing order of keys. For every key
with duplicate values, only the first record is yielded. When the source is
an object store or a unique index, this direction has the exact same behavior as "next".
"prev". This direction causes the cursor to be opened at the end of the
source. When iterated, the cursor should yield all records, including
duplicates, in monotonically decreasing order of keys."prevunique". This direction causes the cursor to be opened at the end of the
source. When iterated, the cursor should not yield records with
the same key, but otherwise yield all records, in monotonically decreasing order of keys. For every key
with duplicate values, only the first record is yielded. When the source is
an object store or a unique index, this direction has the exact same behavior as "prev".
If the source of a cursor is an object store, the effective object store
of the cursor is that object store and the effective key of the cursor is the cursor's position.
If the source of a cursor is an index, the effective object store
of the cursor is that index's referenced object store and the effective key is the cursor's
object store position.
It is possible for the list of records which the cursor is iterating over to
change before the full range of the cursor has been iterated. In order to
handle this, cursors maintain their position not as an index, but rather
as a key of the previously returned record. For a forward iterating cursor,
the next time the cursor is asked to iterate to the next record it returns the
record with the lowest key greater than the one previously returned. For
a backwards iterating cursor, the situation is opposite and it returns the record
with the highest key less than the one previously returned.
For cursors iterating indexes the situation is a little bit more complicated since
multiple records can have the same key and are therefore also sorted by value.
When iterating indexes the cursor also has an object store position, which indicates
the value of the previously found record in the index. Both
position and the object store position are used when finding the next appropriate record.
Cursor objects implement the IDBCursor
or the IDBCursorSync interfaces. There is only ever one
IDBCursor or IDBCursorSync instance representing
a given cursor. However there is no limit on how many cursors can be used at the
same time.
3.1.11 Exceptions
Each of the exceptions defined in the IndexedDB spec is a DOMException with a specific type. [DOM4]
Existing DOM Level 4 exceptions will set their code to a
legacy value; however, the new indexedDB type exceptions will have a
code value of 0.
The message value is optional.
IndexedDB uses the following new DOMException types with their various messages.
All of these new types will have a code value of 0 zero.
| Type |
Message (Optional) |
UnknownError |
The operation failed for reasons unrelated to the database itself and not covered by any other errors. |
ConstraintError |
A mutation operation in the transaction failed because a constraint was not satisfied.
For example, an object such as an object store or index already exists and a request attempted to create a new one.
|
DataError |
Data provided to an operation does not meet requirements. |
TransactionInactiveError |
A request was placed against a transaction which is currently not active, or which is finished. |
ReadOnlyError |
The mutating operation was attempted in a "readonly" transaction. |
VersionError |
An attempt was made to open a database using a lower version than the existing version. |
IndexedDB reuses the following existing DOMException types from [DOM4].
These types will continue to return the codes and names as specified in DOM4;
however, they will have the following messages when thrown from an IndexedDB API:
| Type |
Message (Optional) |
NotFoundError |
The operation failed because the requested database object could not be found.
For example, an object store did not exist but was being opened.
|
InvalidStateError |
An operation was called on an object on which it is not allowed or at a time when it is not allowed.
Also occurs if a request is made on a source object that has been deleted or removed.
Use TransactionInactiveError or ReadOnlyError when possible, as they are more specific variations of InvalidStateError.
|
InvalidAccessError |
An invalid operation was performed on an object. For example transaction creation attempt was made,
but an empty scope was provided.
|
AbortError |
A request was aborted, for example through a call to IDBTransaction.abort.
|
TimeoutError |
A lock for the transaction could not be obtained in a reasonable time. |
QuotaExceededError |
The operation failed because there was not enough remaining storage space,
or the storage quota was reached and the user declined to give more space to the database.
|
SyntaxError |
The keypath argument contains an invalid key path. |
DataCloneError |
The data being stored could not be cloned by the internal structured cloning algorithm. |
3.1.12 Options Object
Options objects are dictionary objects [WEBIDL]
which are used to supply optional parameters to some indexedDB functions like
createObjectStore and
createIndex. The attributes on the object
correspond to optional parameters on the function called.
IDL
The following WebIDL defines IDBObjectStoreParameters dictionary type.
dictionary IDBObjectStoreParameters {
DOMString? keyPath = null;
boolean autoIncrement = false;
};
The following WebIDL defines IDBIndexParameters dictionary type.
dictionary IDBIndexParameters {
boolean unique = false;
boolean multiEntry = false;
};
The following WebIDL defines IDBVersionChangeEventInit dictionary type.
dictionary IDBVersionChangeEventInit : EventInit {
unsigned long long oldVersion = 0;
unsigned long long? newVersion = null;
};
3.1.13 Key Generators
When a object store is created it can be specified to use a key generator.
A key generator keeps an internal current number. The current number
is always a positive integer. Whenever the key generator is used to generate a new key, the
generator's current number is returned and then incremented to prepare
for the next time a new key is needed. Implementations must use the following rules
for generating numbers when a key generator is used.
-
Every object store that uses key generators use a seprate generator. I.e. interacting with one
object store never affects the key generator of any other object store.
-
The current number of a key generator is always set to
1 when the
object store for that key generator is first created.
-
When a key generator is used to generate a new key for a object store, the
key generator's current number is used as the new key value and then the
key generator's current number is increased by
1.
-
When a record is stored in a object store which uses a key generator, and an explicit
key is defined, if the key's value is a
float greater than or equal to the
key generator's current number, then the key generator's current number is set
to the smallest integer number larger than the explicit key. Only explicit keys which
are float values affect the current number of the key generator.
Dates and Arrays which contain floats do not affect
the current number of the key generator. Likewise, negative float numbers
do not affect the current number since they are always lower than the current
number.
This can happen both with in-line keys, if the property of the stored value is set,
or with out-of-line keys, if an explicit key argument is provided.
-
Modifying a key generator's current number is considered part of a database operation.
This means that if the operation fails and the operation is reverted, the current number
is reverted to the value it had before the operation started. This applies both to modifications
that happen due to the current number getting increased by
1 when the key
generator is used, and to modifications that happen due to
-
Likewise, if a transaction is aborted, the current number of the key generator's
for all object stores in the transaction's scope is reverted to the values they
had before the transaction was started.
-
When the current number of a key generator reaches above the value
2^53
(9007199254740992) any attempts to use the key generator to generate a new
key will result in an error. It's still possible to insert records into the
object store by specifying an explicit key, however the only way to use a key generator
again for the object store is to delete the object store and create a new one.
Note that as long as key generators are used in a normal fashion this will not be a problem.
If you generate a new key 1000 times per second day and night, you won't run into this limit
for over 285000 years.
-
The current number for a key generator never decreases, other than as a result of
database operations being reverted. Deleting a record from an object store
never affects the object store's key generator. Even clearing all records from an
object store, for example using the
clear() function, does
not affect the current number of the object store's key generator.
A practical result of this is that the first key generated for an object store is always 1
(unless a higher numeric key is inserted first) and the key generated for an object store is always a
positive integer higher than the highest numeric key in the store. The same key is never generated
twice for the same object store unless a transaction is rolled back.
Each object store gets it's own key generator:
ECMAScript
store1 = db.createObjectStore("store1", { autoIncrement: true });
store1.put("a"); // Will get key 1
store2 = db.createObjectStore("store2", { autoIncrement: true });
store2.put("a"); // Will get key 1
store1.put("b"); // Will get key 2
store2.put("b"); // Will get key 2
If an insertion fails due to constraint violations or IO error, the
key generator is not updated.
ECMAScript
transaction.onerror = function(e) { e.preventDefault() };
store = db.createObjectStore("store1", { autoIncrement: true });
index = store.createIndex("index1", "ix", { unique: true });
store.put({ ix: "a"}); // Will get key 1
store.put({ ix: "a"}); // Will fail
store.put({ ix: "b"}); // Will get key 2
Removing items from an objectStore never affects the key generator.
Including when .clear() is called.
ECMAScript
store = db.createObjectStore("store1", { autoIncrement: true });
store.put("a"); // Will get key 1
store.delete(1);
store.put("b"); // Will get key 2
store.clear();
store.put("c"); // Will get key 3
store.delete(IDBKeyRange.lowerBound(0));
store.put("d"); // Will get key 4
Inserting an item with an explicit key affects the key generator if,
and only if, the key is numeric and higher than the last generated
key.
ECMAScript
store = db.createObjectStore("store1", { autoIncrement: true });
store.put("a"); // Will get key 1
store.put("b", 3); // Will use key 3
store.put("c"); // Will get key 4
store.put("d", -10); // Will use key -10
store.put("e"); // Will get key 5
store.put("f", 6.00001); // Will use key 6.0001
store.put("g"); // Will get key 7
store.put("f", 8.9999); // Will use key 8.9999
store.put("g"); // Will get key 9
store.put("h", "foo"); // Will use key "foo"
store.put("i"); // Will get key 10
store.put("j", [1000]); // Will use key [1000]
store.put("k"); // Will get key 11
// All of these would behave the same if the objectStore used a
keyPath and the explicit key was passed inline in the object
Aborting a transaction rolls back any increases to the key generator
which happened during the transaction. This is to make all rollbacks
consistent since rollbacks that happen due to crash never has a chance
to commit the increased key generator value.
ECMAScript
db.createObjectStore("store", { autoIncrement: true });
trans1 = db.transaction(["store"], "readwrite");
store_t1 = trans1.objectStore("store");
store_t1.put("a"); // Will get key 1
store_t1.put("b"); // Will get key 2
trans1.abort();
trans2 = db.transaction(["store"], "readwrite");
store_t2 = trans2.objectStore("store");
store_t2.put("c"); // Will get key 1
store_t2.put("d"); // Will get key 2
3.2 Asynchronous APIs
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.
3.2.1 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].
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', 15);
request.onsuccess = function(evt) {...};
request.onerror = function(evt) {...};
interface IDBRequest : EventTarget {
readonly attribute any result;
readonly attribute DOMError error;
readonly attribute Object source;
readonly attribute IDBTransaction transaction;
readonly attribute DOMString readyState;
[TreatNonCallableAsNull]
attribute Function? onsuccess;
[TreatNonCallableAsNull]
attribute Function? onerror;
};
Attributes
error of type DOMError, readonly-
When the done flag is true, getting this
property must return the error of
the request. This is null when no error occurred. When the
done flag is false, getting this property
must throw a
DOMException of type InvalidStateError.
| Exception | On Get | On Set | Description |
|---|
| DOMException | ✔ | ✘ | InvalidStateError | Thrown when this attribute was read when the done flag was set to false. |
|
onerror of type Function, nullable- The event handler for the error event
No exceptions.
onsuccess of type Function, nullable- The event handler for the success event
No exceptions.
readyState of type DOMString, readonly- When the done flag is false, returns
"pending", otherwise returns
"done".No exceptions.
result of type any, readonly-
When the done flag is true, getting this
property must return the result of
the request. This is
undefined when the request resulted
in an error. When the done flag is
false, getting this property must throw a DOMException of type InvalidStateError.
| Exception | On Get | On Set | Description |
|---|
| DOMException | ✔ | ✘ | InvalidStateError | Thrown when this attribute was read when the done flag was set to false. |
|
source of type Object, readonly-
Getting this property must return the source
for the request. Returns
null when there is no source set.
No exceptions.
transaction of type IDBTransaction, readonly-
Getting this property must return the transaction
for the request. This property can be null for certain requests, such as for request
returned from IDBFactory.open.
No exceptions.
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 IDBFactoryblocked event and upgradeneeded event easier.
interface IDBOpenDBRequest : IDBRequest {
[TreatNonCallableAsNull]
attribute Function? onblocked;
[TreatNonCallableAsNull]
attribute Function? onupgradeneeded;
};
Attributes
onblocked of type Function, nullable- The event handler for the
blocked eventNo exceptions.
onupgradeneeded of type Function, nullable- The event handler for the
upgradeneeded eventNo exceptions.
The task source for these tasks is the
database access task source.
3.2.2 Event interfaces
This specification fires events with the following custom interfaces:
[Constructor(DOMString type, optional IDBVersionChangeEventInit eventInitDict)]
interface IDBVersionChangeEvent : Event {
readonly attribute unsigned long long oldVersion;
readonly attribute unsigned long long? newVersion;
};
3.2.3 Opening a database
Window and
WorkerUtils objects
must implement the IDBEnvironment interface.
Window implements IDBEnvironment;
WorkerUtils 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.
interface IDBFactory {
IDBOpenDBRequest open (DOMString name, [EnforceRange] optional unsigned long long version);
IDBOpenDBRequest deleteDatabase (DOMString name);
short cmp (any first, any second);
};
Methods
cmp-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| first | any | ✘ | ✘ | The first key to compare. |
| second | any | ✘ | ✘ | The second key to compare. |
deleteDatabase-
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 created request has no source and must implement the
IDBVersionChangeRequest interface.
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.
No exceptions.
open-
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.
| Exception | Description |
|---|
| DOMException | TypeError | The value of version is 0 (zero) or a negative number. |
|
3.2.4 Database
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.
interface IDBDatabase : EventTarget {
readonly attribute DOMString name;
readonly attribute unsigned long long version;
readonly attribute DOMStringList objectStoreNames;
IDBObjectStore createObjectStore (DOMString name, optional IDBObjectStoreParameters optionalParameters);
void deleteObjectStore (DOMString name);
IDBTransaction transaction (any storeNames, optional DOMString mode);
void close ();
[TreatNonCallableAsNull]
attribute Function? onabort;
[TreatNonCallableAsNull]
attribute Function? onerror;
[TreatNonCallableAsNull]
attribute Function? onversionchange;
};
Attributes
name of type DOMString, readonly-
On getting, this attribute must return the name
of the connected database. The function must
return this name even if the closePending flag is set on the connection.
In other words, the return value from this function
stays constant for the lifetime of the
IDBDatabase instance.
No exceptions.
objectStoreNames of type DOMStringList, readonly-
On getting, this attribute must return a list of names of the
object stores currently in the
connected database. The list must
be sorted in ascending order using the algorithm defined by step 4
of section 11.8.5, The Abstract Relational Comparison Algorithm
of the ECMAScript Language Specification [ECMA-262].
Once the closePending flag is set on the connection, this
function must return a snapshot of the list of names of the object
stores taken at the time when the
close method was called. Even if
other connections are later used to change the set of object
stores that exist in the database. In other words, the return
value from this function stays constant for the lifetime of the
IDBDatabase instance, except during a "versionchange"
transaction if createObjectStore
or deleteObjectStore
is called on this IDBDatabase instance itself.
No exceptions.
onabort of type Function, nullable- The event handler for the abort event.
No exceptions.
onerror of type Function, nullable- The event handler for the error event.
No exceptions.
onversionchange of type Function, nullable- The event handler for the versionchange event.
No exceptions.
version of type unsigned long long, readonly-
On getting, this attribute must return the version of the
database when this
IDBDatabase instance was created.
When a IDBDatabase instance is created,
this is always the number passed as the version
argument passed to the open
call used to create the IDBDatabase instance. This value remains constant for the lifetime of the IDBDatabase object.
If the connection is closed, this attribute represents a
snapshot of the version that the database had when the connection
was closed. Even if another connection is later used to modify the
version, that attribute on closed instances are not changed.
No exceptions.
Methods
close-
This method returns immediately and performs the steps for closing a database connection.
No parameters.
No exceptions.
createObjectStore-
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 an Array and any items in the array is not a valid key path,
or if keyPath is a string and is not a valid key path then a
DOMException of type SyntaxError must be thrown. Otherwise set the created object store's
key path is set 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.
| Exception | Description |
|---|
| DOMException | InvalidStateError | This method was not called from a "versionchange"
transaction callback. Also occurs if a request is made on a source object that has been deleted or removed. | ConstraintError | An object store with the same name, compared in a
case-sensitive manner, already exists in the
connected database. | InvalidAccessError | If autoIncrement is set to true, and keyPath either is the empty string, or an Array containing the empty string. |
|
deleteObjectStore-
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.
transaction-
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.
| Exception | Description |
|---|
| DOMException | InvalidStateError |
The close() method has been called on this IDBDatabase instance.
| NotFoundError | One of the names provided in the storeNames argument doesn't exist in this database. | TypeError | The value for the mode parameter is invalid. | InvalidAccessError | The function was called with an empty list of store names |
|
3.2.5 Object Store
Object store objects implement the following
interface:
interface IDBObjectStore {
readonly attribute DOMString name;
readonly attribute DOMString keyPath;
readonly attribute DOMStringList indexNames;
readonly attribute IDBTransaction transaction;
readonly attribute boolean autoIncremenent;;
IDBRequest put (any value, optional any key);
IDBRequest add (any value, optional any key);
IDBRequest delete (any key);
IDBRequest get (any key);
IDBRequest clear ();
IDBRequest openCursor (optional any? range, optional DOMString direction);
IDBIndex createIndex (DOMString name, any keyPath, optional IDBIndexParameters optionalParameters);
IDBIndex index (DOMString name);
void deleteIndex (DOMString indexName);
IDBRequest count (optional any key);
};
Attributes
autoIncremenent; of type boolean, readonly- On getting, provides the auto increment flag for this object store.
No exceptions.
indexNames of type DOMStringList, readonly-
On getting, provide a list of the names of indexes on
objects in this object store. The list must
be sorted in ascending order using the algorithm defined by step 4
of section 11.8.5, The Abstract Relational Comparison Algorithm
of the ECMAScript Language Specification [ECMA-262].
No exceptions.
keyPath of type DOMString, readonly-
On getting, provide the key path
of this object store. This will be either a
DOMString,
an Array of DOMStrings or null.
No exceptions.
name of type DOMString, readonly-
On getting, provide the name of this
object store.
No exceptions.
transaction of type IDBTransaction, readonly-
On getting, returns the transaction this object store belongs to.
No exceptions.
Methods
add-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| value | any | ✘ | ✘ | The value to be stored in the record |
| key | any | ✘ | ✔ | The key used to identify the record |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBObjectStore belongs to is not active. | ReadOnlyError | The mode of the associated transaction is "readonly". | DataError | The calculated key for the insertion was not a valid key. Also thrown if the
calculated key for any of the indexes which belong to this object store had a calculated
key which was not a valid key | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. | DataCloneError | The data being stored could not be cloned by the internal
structured cloning algorithm. |
|
clear-
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.
No parameters.
count-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✔ |
Key identifying the record to be retrieved.
This can also be an IDBKeyRange.
|
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBObjectStore belongs to is not active. | DataError | The key parameter is not a valid key or a key range. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
createIndex-
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 an Array and any items in the array is not a valid key path,
or if keyPath is a string and is not a valid key path then a DOMException
of type SyntaxError must be thrown. If keyPath is
and Array and the multiEntry property in the optionalParameters is true,
then a DOMException of type NotSupportedError must be thrown. Otherwise set the created object store's
key path is set 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.
| Exception | Description |
|---|
| DOMException | InvalidStateError | This method was not called from a "versionchange"
transaction callback. Also occurs if a request is made on a source object that has been deleted or removed. | ConstraintError | An index with the same name, compared in a
case-sensitive manner, already exists in the
connected database. |
|
delete-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✘ | Key identifying the record to be deleted |
deleteIndex-
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.
get-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✘ | Key identifying the record to be retrieved. This can also be an IDBKeyRange in which case
the function retreives the first existing value in that range. |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBObjectStore belongs to is not active. | DataError | The key parameter was not passed a valid value. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
index-
Returns an
IDBIndex representing an index that is part of the
object store. Every call to this function on the same
IDBObjectStore instance and with the same name returns the same IDBIndex instance.
However the retured IDBIndex instance is specific to this IDBObjectStore instance. If this
function is called on a different IDBObjectStore instance, a different IDBIndex instance is
returned. A result of this is that different IDBTransactions use different IDBIndex instances
to represent the same index.
| Exception | Description |
|---|
| DOMException | NotFoundError | There is no index with the given name, compared in a
case-sensitive manner, in the connected database. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed, or if the transaction the object store belongs to has finished. |
|
openCursor-
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.
put-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| value | any | ✘ | ✘ | The value to be stored in the record |
| key | any | ✘ | ✔ | The key used to identify the record |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBObjectStore belongs to is not active. | ReadOnlyError | The mode of the associated transaction is "readonly". | DataError | The calculated key for the insertion was not a valid key. Also thrown if the
calculated key for any of the indexes which belong to this object store had a calculated
key which was not a valid key | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. | DataCloneError | The data being stored could not be cloned by the internal
structured cloning algorithm. |
|
3.2.6 Index
Index objects implement the following interface:
interface IDBIndex {
readonly attribute DOMString name;
readonly attribute IDBObjectStore objectStore;
readonly attribute DOMString keyPath;
readonly attribute boolean multiEntry;
readonly attribute boolean unique;
IDBRequest openCursor (optional any? range, optional DOMString direction);
IDBRequest openKeyCursor (optional any? range, optional DOMString direction);
IDBRequest get (any key);
IDBRequest getKey (any key);
IDBRequest count (optional any key);
};
Attributes
keyPath of type DOMString, readonly-
On getting, provide the key path
of this object store. This will be either a
DOMString or
an Array of DOMStrings.
No exceptions.
multiEntry of type boolean, readonly-
On getting, provide the multiEntry flag of this index.
No exceptions.
name of type DOMString, readonly-
On getting, provide the name of this index.
No exceptions.
objectStore of type IDBObjectStore, readonly-
On getting, returns a reference to the
IDBObjectStore instance for the
referenced object store in this IDBIndex's transaction. This must
return the same IDBObjectStore instance as was used to get a reference
to this IDBIndex.
No exceptions.
unique of type boolean, readonly-
On getting, provide the unique flag of this index.
No exceptions.
Methods
count-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✔ |
Key identifying the record to be retrieved.
This can also be an IDBKeyRange.
|
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBIndex belongs to is not active. | DataError | The key parameter is not a valid key or a key range. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
get-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✘ | Key identifying the record to be retrieved. This can also be an IDBKeyRange in which case
the function retreives the first existing value in that range. |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBIndex belongs to is not active. | DataError | The key parameter was not passed a valid value. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
getKey-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✘ | Key identifying the record to be retrieved. This can also be an IDBKeyRange in which case
the function retreives the first existing value in that range. |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBIndex belongs to is not active. | DataError | The key parameter was not passed a valid value. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
openCursor-
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
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBIndex belongs to is not active. | TypeError | The value for the direction parameter is invalid. | DataError | The range parameter was not passed key range or a valid key. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
openKeyCursor-
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
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBIndex belongs to is not active. | TypeError | The value for the direction parameter is invalid. | DataError | The range parameter was not passed key range or a valid key. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
3.2.7 Cursor
Cursor objects implement the following interface:
interface IDBCursor {
readonly attribute Object source;
readonly attribute DOMString direction;
readonly attribute any key;
readonly attribute any primaryKey;
IDBRequest update (any value);
void advance ([EnforceRange] unsigned long count);
void continue (optional any key);
IDBRequest delete ();
};
Attributes
direction of type DOMString, readonly-
On getting, provide the traversal direction of the cursor.
No exceptions.
key of type any, readonly- Returns the cursor's current key.
Note that if this property returns an object (specifically an
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.No exceptions.
primaryKey of type any, readonly- Returns the cursor's current effective key.
Note that if this property returns an object (specifically an
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.No exceptions.
source of type Object, readonly-
On getting, returns the
IDBObjectStore or IDBIndex
which this cursor is iterating. This function
never returns null or throws an exception, even if the
cursor is currently being iterated, has iterated past its end,
or its transaction is not active.
No exceptions.
Methods
advance-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| count | unsigned long | ✘ | ✘ | The number of advances forward the cursor should make. |
| Exception | Description |
|---|
| DOMException | TypeError | The value passed into the count parameter was zero or a negative number. | TransactionInactiveError | The transaction this IDBCursor belongs to is not active. | InvalidStateError | The cursor is currently being iterated, or has iterated past its end. |
|
continue-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✔ | The next key to position this cursor at |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBCursor belongs to is not active. | InvalidStateError | The cursor is currently being iterated, or has iterated past its end. | DataError | The key parameter was specified but did not contain a valid key. |
|
delete-
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.
No parameters.
update-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| value | any | ✘ | ✘ | The new value to store at the current position. |
interface IDBCursorWithValue : IDBCursor {
readonly attribute any value;
};
Attributes
value of type any, readonly- Returns the cursor's current value.
Note that if this property returns an object, it returns the same
object instance every time it is inspected, until the cursor's value 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.
No exceptions.
3.2.8 Transaction
Transaction objects implement the following interface:
interface IDBTransaction : EventTarget {
readonly attribute DOMString mode;
readonly attribute IDBDatabase db;
readonly attribute DOMError error;
IDBObjectStore objectStore (DOMString name);
void abort ();
[TreatNonCallableAsNull]
attribute Function? onabort;
[TreatNonCallableAsNull]
attribute Function? oncomplete;
[TreatNonCallableAsNull]
attribute Function? onerror;
};
Attributes
db of type IDBDatabase, readonly- The database connection of which this transaction
is a part
No exceptions.
error of type DOMError, readonly-
When the done flag is true, getting this
property must return the error of the request that caused the transaction to be aborted.
If the error was generated when committing the transaction and not from an individual request,
the error must contain the reasons for the transaction failure (e.g.
QuotaExceededError, UnknownError).
This is null when no error occurred or when the transaction is programmatically aborted.
When the done flag is false,
getting this property must throw a DOMException of type InvalidStateError.
| Exception | On Get | On Set | Description |
|---|
| DOMException | ✔ | ✘ | InvalidStateError | Thrown when this attribute was read when the done flag was set to false. |
|
mode of type DOMString, 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, nullable- The event handler for the abort event.
No exceptions.
oncomplete of type Function, nullable- The event handler for the complete event.
No exceptions.
onerror of type Function, nullable- The event handler for the error event.
No exceptions.
3.3 Synchronous APIs
The features in Section 3.3 Synchronous APIs are at risk and may be removed, due to potential lack of implementations.
The synchronous database API methods provide a blocking access pattern to IndexedDB
databases. Since they block the calling thread they are only available from workers.
3.3.1 Opening a database
WorkerUtils 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.
interface IDBFactorySync {
IDBDatabaseSync open (DOMString name, [EnforceRange] optional unsigned long long version, optional IDBVersionChangeCallback upgradeCallback, optional unsigned long timeout);
void deleteDatabase (DOMString name);
short cmp (any first, any second);
};
Methods
cmp-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| first | any | ✘ | ✘ | The first key to compare. |
| second | any | ✘ | ✘ | The second key to compare. |
deleteDatabase-
When invoked, this method synchronously runs the steps for deleting a database.
Let origin be the origin of the IDBEnvironmentSync used to access
this IDBFactorySync and name be the name argument passed
to this function.
If an error is returned from the steps above, then the implementation must
throw a DOMException with its name and message set to appropriate values for the error.
No exceptions.
open-
When invoked, this method must throw a DOMException of type InvalidStateError
when it is called within the IDBTransactionCallback of a transaction
method or the IDBVersionChangeCallback of a open method. Otherwise this method
synchronously runs the steps for opening a database. Let origin be the origin of the
IDBEnvironmentSync used to access this IDBFactorySync, name, version
and upgrade callback be the name, version and upgradeCallback
arguments passed to this function.
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 a timeout parameter was supplied, then this limits the total waiting time allowed in
step 3 of steps for opening a database and step 4 of the steps for running a
"versionchange" transaction. If more waiting time would be needed in order to progress,
then abort those algorithms and throw a DOMException of type TimeoutError.
The timeout parameter does not affect how long the upgradeCallback can run.
If an error is returned from the steps above, then the implementation must
throw a DOMException with its name and message set to appropriate values for the error.
If the steps above are successful, the implementation must create an IDBDatabaseSync
object representing the created connection and return it.
Processing a open call may take a long time as it could require running a
"versionchange" transaction which requires all other connections to the database to be closed, which
in turn may depend on user input or other long-running tasks. If blocking for a long period of time
is not acceptable for a given scenario then the asynchronous API should be used for version changes.
If the value for version is 0 (zero) or a negative number, this method must
throw a JavaScript TypeError exception.
| Exception | Description |
|---|
| DOMException | InvalidStateError |
The open method was called within the IDBTransactionCallback of a
transaction method or IDBVersionChangeCallback of a
open method.
| TimeoutError |
Was unable to open the database with the requested version within the given timeout period.
| TypeError | The value of version is 0 (zero) or a negative number. |
|
3.3.2 Database
A database object provides access to the schema and data of a particular database.
interface IDBDatabaseSync {
readonly attribute DOMString name;
readonly attribute unsigned long long version;
readonly attribute DOMStringList objectStoreNames;
IDBObjectStoreSync createObjectStore (DOMString name, optional IDBObjectStoreParameters optionalParameters);
void deleteObjectStore (DOMString name);
void transaction (any storeNames, IDBTransactionCallback callback, optional DOMString mode, optional unsigned long timeout);
void close ();
};
Attributes
name of type DOMString, readonly-
On getting, this attribute must return the name
of the connected database. The function must
return this name even if the closePending flag is set on the connection.
In other words, the return value from this function
stays constant for the lifetime of the
IDBDatabaseSync instance.
No exceptions.
objectStoreNames of type DOMStringList, readonly-
On getting, this attribute must return a list of names of the
object stores currently in the
connected database. The list must
be sorted in ascending order using the algorithm defined by step 4
of section 11.8.5, The Abstract Relational Comparison Algorithm
of the ECMAScript Language Specification [ECMA-262].
Once the closePending flag is set on the connection, this
function must return a snapshot of the list of names of the object
stores taken at the time when the
close method was called. Even if
other connections are later used to change the set of object
stores that exist in the database. In other words, the return
value from this function stays constant for the lifetime of the
IDBDatabaseSync instance except during a "versionchange"
transaction if
createObjectStore
or deleteObjectStore
is called on this IDBDatabaseSync instance itself.
No exceptions.
version of type unsigned long long, readonly-
On getting, this attribute must return the version of the
database when this
IDBDatabaseSync instance was created.
When a IDBDatabaseSync instance is created,
this is always the number passed as the version
argument passed to the open
call used to create the IDBDatabaseSync instance. This value remains constant for the lifetime of the IDBDatabaseSync object.
If the connection is closed, this attribute represents a
snapshot of the version that the database had when the connection
was closed. Even if another connection is later used to modify the
version, that attribute on closed instances are not changed.
No exceptions.
Methods
close-
This method synchronously performs the steps for closing a database connection and returns once
the database has been closed.
No parameters.
No exceptions.
createObjectStore-
This method creates and returns a new object store with the
given name in the connected database. This method
should only be called from inside a "versionchange" transaction.
This method synchronously modifies the
IDBDatabaseSync.objectStoreNames property. However it
only modifies the IDBDatabaseSync.objectStoreNames
property on the IDBDatabaseSync instance on which it was called.
If the optionalParameters argument is specified and has a keyPath property
which is not 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 an Array and any items in the array is not a valid key path,
or if keyPath is a string and is not a valid key path then a
DOMException of type SyntaxError must be thrown. Otherwise set the created object store's
key path is set 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.
| Exception | Description |
|---|
| DOMException | InvalidStateError |
This method was not called from a "versionchange" transaction.
Also occurs if a request is made on a source object that has been deleted or removed.
| ConstraintError | If an object store with the same name, compared in a case-sensitive
manner, already exists in the connected
database. | InvalidAccessError | If autoIncrement is set to true, and keyPath either is the empty string, or an Array containing the empty string. |
|
deleteObjectStore-
This method destroys an object store with the
given name as well as all indexes that are
referencing that object store. This method
should only be called from inside a "versionchange" transaction.
This method synchronously modifies the
IDBDatabaseSync.objectStoreNames property. However it
only modifies the IDBDatabaseSync.objectStoreNames
property on the IDBDatabaseSync instance on which it was called.
| Exception | Description |
|---|
| DOMException | InvalidStateError |
This method was not called from a "versionchange" transaction callback.
Also occurs if a request is made on a source object that has been deleted or removed.
| NotFoundError |
If the object store with the given name, compared in a
case-sensitive manner, does not already exist
in the connected database.
|
|
transaction-
This method, when called must execute the
steps for creating a transaction in a sychronous
fashion. The storeNames, callback, mode, and
timeout arguments are forwarded to the algorithm as-is. The connection
argument is set to the IDBDatabaseSync that the transaction() method was
called on.
The method returns an IDBTransactionSync object representing the transaction
returned by the steps above.
This method must throw an DOMException of type InvalidStateError
when it is called within the IDBTransactionCallback of a transaction method or the
IDBVersionChangeCallback of a open method.
| Exception | Description |
|---|
| DOMException | TimeoutError |
If starting the transaction takes longer than the specified timeout.
| InvalidStateError |
The close() method has been called on this IDBDatabase instance.
Also thrown when The transaction() method was called within the
IDBTransactionCallback of a transaction method or the
IDBVersionChangeCallback of a open method. | NotFoundError | One of the names provided in the storeNames argument doesn't exist in this database. | TypeError | The value for the mode parameter is invalid. | InvalidAccessError | The function was called with an empty list of store names |
|
[NoInterfaceObject, Callback]
interface IDBTransactionCallback {
void transactionStarted (IDBTransactionSync transaction);
};
Methods
transactionStarted-
Called once the transaction is allowed to run. The actions taken in this function make up
the body of the transaction.
| Parameter | Type | Nullable | Optional | Description |
|---|
| transaction | IDBTransactionSync | ✘ | ✘ | The newly started transaction |
No exceptions.
[NoInterfaceObject, Callback]
interface IDBVersionChangeCallback {
void transactionStarted (IDBTransactionSync transaction, unsigned long long oldVersion);
};
Methods
transactionStarted-
Called if a database upgrade is needed once the transaction used to upgrade the database is allowed to run.
The actions taken in this function make up the body of the transaction.
| Parameter | Type | Nullable | Optional | Description |
|---|
| transaction | IDBTransactionSync | ✘ | ✘ | The newly started transaction |
| oldVersion | unsigned long long | ✘ | ✘ | The version that the database had before the upgrade was needed. 0 if the database was newly created. |
No exceptions.
3.3.3 Object Store
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 = indexedDBSync.open('AddressBook', 1, function(trans, oldVersion) {
trans.db.createObjectStore('Contact', {keyPath:'id', autoIncrement:true} );
});
Using this database, we can store records in the Contact
object store.
ECMAScript
var tx = db.transaction();
var store = tx.objectStore('Contact');
var contact = store.add({name: 'Lincoln', number: '7012'});
// 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 put operation will overwrite the record stored by the first
add operation with the same key.
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();
interface IDBObjectStoreSync {
readonly attribute DOMString name;
readonly attribute any keyPath;
readonly attribute DOMStringList indexNames;
readonly attribute IDBTransactionSync transaction;
readonly attribute boolean autoIncremenent;;
any put (any value, optional any key);
any add (any value, optional any key);
boolean delete (any key);
any get (any key);
void clear ();
IDBIndexSync createIndex (DOMString name, any keyPath, optional IDBIndexParameters optionalParameters);
IDBIndexSync index (DOMString name);
void deleteIndex (DOMString indexName);
IDBCursorWithValueSync openCursor (optional any? range, optional DOMString direction);
unsigned long count (optional any key);
};
Attributes
autoIncremenent; of type boolean, readonly- On getting, provides the auto increment flag for this object store.
No exceptions.
indexNames of type DOMStringList, readonly-
On getting, provide a list of the names of indexes on
objects in this object store. The list must
be sorted in ascending order using the algorithm defined by step 4
of section 11.8.5, The Abstract Relational Comparison Algorithm
of the ECMAScript Language Specification [ECMA-262].
No exceptions.
keyPath of type any, readonly-
On getting, provide the key path
of this object store. This will be either a
DOMString,
an Array of DOMStrings or null.
No exceptions.
name of type DOMString, readonly-
On getting, provide the name of this
object store.
No exceptions.
transaction of type IDBTransactionSync, readonly-
On getting, returns the transaction this object store belongs to.
No exceptions.
Methods
add-
This method throws a DOMException of type ReadOnlyError if the transaction which this IDBObjectStoreSync 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 synchronously executing a request and return the key of the stored object.
The steps are run with this IDBObjectStoreSync as source and the steps for
storing a record into an object store as operation, using this IDBObjectStoreSync
as store, the created clone as value, the key parameter as
key, and with the no-overwrite flag flag set to true.
| Parameter | Type | Nullable | Optional | Description |
|---|
| value | any | ✘ | ✘ | The value to be stored in the record |
| key | any | ✘ | ✔ | The key used to identify the record |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBObjectStoreSync belongs to is not active. | ReadOnlyError | The mode of the associated transaction is "readonly". | DataError | The calculated key for the insertion was not a valid key. Also thrown if the
calculated key for any of the indexes which belong to this object store had a calculated
key which was not a valid key | ConstraintError | A record
exists in this object store for the key key parameter, or another record
in this object store has the same value for the keyPath of a unique index.
| InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. | DataCloneError | The data being stored could not be cloned by the internal
structured cloning algorithm. |
|
clear-
This method throws a DOMException of type ReadOnlyError if the transaction which this IDBObjectStoreSync belongs to is
has its mode set to "readonly".
Otherwise this method runs the steps for synchronously executing a request. The steps
are run with this IDBObjectStoreSync as source and the
steps for clearing an object store as operation, using
this IDBObjectStoreSync as store.
No parameters.
count-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✔ |
Key identifying the record to be retrieved.
This can also be an IDBKeyRange.
|
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 "versionchange" transaction. 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 an Array and any items in the array is not a valid key path,
or if keyPath is a string and is not a valid key path, then a DOMException
of type SyntaxError must be thrown. If keyPath is
and Array and the multiEntry property in the optionalParameters is true,
then a DOMException of type NotSupportedError must be thrown. Otherwise set the created object store's
key path is set to the value of keyPath.
| Exception | Description |
|---|
| DOMException | InvalidStateError | This method was not called from a "versionchange"
transaction. Also occurs if a request is made on a source object that has been deleted or removed. | ConstraintError | An index with the same name, compared in a
case-sensitive manner, already exists in the
connected database.
Also thrown when creating a unique index on top of an object store
that already contains records that violate the unique constraint. |
|
delete-
This method throws a DOMException of type ReadOnlyError if the transaction which this IDBObjectStoreSync 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 synchronously executing a request.
The steps are run with this IDBObjectStoreSync as source and the steps for deleting
records from an object store as operation, using this IDBObjectStoreSync
as store and the key parameter as key. The function returns the result
of running these steps.
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✘ | Key identifying the record to be deleted |
deleteIndex-
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.
get-
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 synchronously executing
a request and returns the result of the operation. The steps are run with this
IDBObjectStoreSync as source and the steps for retrieving a value from an
object store as operation, using this IDBObjectStoreSync 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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✘ | Key identifying the record to be retrieved. This can also be an IDBKeyRange in which case
the function retrieves the first existing value in that range. |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBObjectStoreSync belongs to is not active. | DataError | The key parameter was not passed a valid value. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
index-
Returns an
IDBIndexSync representing an index that is part of the
object store. Every call to this function on the same
IDBObjectStoreSync instance and with the same name returns the same IDBIndexSync instance.
However the retured IDBIndexSync instance is specific to this IDBObjectStoreSync instance. If this
function is called on a different IDBObjectStoreSync instance, a different IDBIndexSync instance is
returned. A result of this is that different IDBTransactionSyncs use different IDBIndexSync instances
to represent the same index.
openCursor-
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 IDBCursorWithValueSync 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 IDBObjectStoreSync 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 synchronously executing a request and returns the result of the operation, in
this case an IDBCursorSync object. The steps are run with this IDBObjectStoreSync as source and the
steps for iterating a cursor as operation,
using the created cursor as cursor and with undefined as key.
put-
This method throws a DOMException of type ReadOnlyError if the transaction which this IDBObjectStoreSync belongs to
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 synchronously executing a request and return the result,
in this case the key of the stored object.
The steps are run with this IDBObjectStoreSync as source and the steps for
storing a record into an object store as operation, using this IDBObjectStoreSync
as store, the created clone as value, the key parameter as
key, and with the no-overwrite flag flag set to false.
| Parameter | Type | Nullable | Optional | Description |
|---|
| value | any | ✘ | ✘ | The value to be stored in the record |
| key | any | ✘ | ✔ | The key used to identify the record |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBObjectStoreSync belongs to is not active. | ReadOnlyError | The mode of the associated transaction is "readonly". | DataError | The calculated key for the insertion was not a valid key. Also thrown if the
calculated key for any of the indexes which belong to this object store had a calculated
key which was not a valid key | ConstraintError | Another record in this object store has the same value for the keyPath of
a unique index.
| InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. | DataCloneError | The data being stored could not be cloned by the internal
structured cloning algorithm. |
|
3.3.4 Index
An index can be created for retrieving records other than
by using record keys. Continuing the earlier example, an
index could be maintained on the name property of objects
in the Contact object store.
ECMAScript
var db = indexedDBSync.open('AddressBook', 2, function(trans, oldVersion) {
if (oldVersion === 1) {
trans.db.createObjectStore('Contact', {keyPath:'id', autoIncrement:true});
}
var store = vtx.objectStore('Contact');
store.createIndex('ContactName', {unique:false, multiEntry:false});
});
For example, the id of an object with the name
property value 'Lincoln' can be retrieved using the
ContactName index.
ECMAScript
var index = store.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 and keys but not the whole 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.openKeyCursor(range);
// each value is a contact id and each key is the name for that
// contact whose name's first letter is either L or M
cursor.continue();
interface IDBIndexSync {
readonly attribute DOMString name;
readonly attribute IDBObjectStoreSync objectStore;
readonly attribute any keyPath;
readonly attribute boolean multiEntry;
readonly attribute boolean unique;
IDBCursorWithValueSync openCursor (optional any? range, optional DOMString direction);
IDBCursorSync openKeyCursor (optional any? range, optional DOMString direction);
any get (any key);
any getKey (any key);
unsigned long count (optional any key);
};
Attributes
keyPath of type any, readonly-
On getting, provide the key path
of this object store. This will be either a
DOMString or
an Array of DOMStrings.
No exceptions.
multiEntry of type boolean, readonly-
On getting, provide the multiEntry flag of this index.
No exceptions.
name of type DOMString, readonly-
On getting, provide the name of this index.
No exceptions.
objectStore of type IDBObjectStoreSync, readonly-
On getting, returns a reference to the
IDBObjectStoreSync instance for the
referenced object store in this IDBIndexSync's transaction. This must
return the same IDBObjectStoreSync instance as was used to get a reference
to this IDBIndexSync.
No exceptions.
unique of type boolean, readonly-
On getting, provide the unique flag of this index.
No exceptions.
Methods
count-
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✔ |
Key identifying the record to be retrieved.
This can also be an IDBKeyRange.
|
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBIndexSync belongs to is not active. | DataError | The key parameter is not a valid key or a key range. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
get-
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 synchronously executing a request
and returns the result from that, in this case an object from the underlying store. The steps are
run with this IDBIndexSync as source and the steps
for retrieving a referenced value from an index as operation, using this IDBIndexSync
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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✘ | Key identifying the record to be retrieved. This can also be an IDBKeyRange in which case
the function retreives the first existing value in that range. |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBIndexSync belongs to is not active. | DataError | The key parameter was not passed a valid value. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
getKey-
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 synchronously executing a request
and returns the result from that, in this case an index value (a key). The steps are
run with the IDBObjectStoreSync associated with this index as source and the steps
for retrieving a value from an index as operation, using this IDBIndexSync
as index and the key parameter as key.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✘ | Key identifying the record to be retrieved. This can also be an IDBKeyRange in which case
the function retreives the first existing value in that range. |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBIndexSync belongs to is not active. | DataError | The key parameter was not passed a valid value. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
openCursor-
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 IDBCursorWithValueSync 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 IDBIndexSync 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 synchronously executing
a request and returns the result, in this case a cursor object. The steps are run with this
IDBIndexSync as source and the steps for iterating a cursor as operation,
using the created cursor as cursor and with undefined as key
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBIndexSync belongs to is not active. | TypeError | The value for the direction parameter is invalid. | DataError | The range parameter was not passed a valid value. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
openKeyCursor-
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 IDBCursorSync interface and must not implement the IDBCursorWithValueSync
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 IDBIndexSync 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 synchronously executing
a request and returns the result, in this case a cursor object. The steps are run with this
IDBIndexSync as source and the steps for iterating a cursor as operation,
using the created cursor as cursor and with undefined as key
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBIndexSync belongs to is not active. | TypeError | The value for the direction parameter is invalid. | DataError | The range parameter was not passed key range or a valid key. | InvalidStateError | Occurs if a request is made on a source object that has been deleted or removed. |
|
3.3.5 Cursor
Using the synchronous API, an application can process all the records
in the cursor's range.
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.
ECMAScript
var tx = db.transaction('Contact');
var store = tx.objectStore('Contact');
var cursor = store.openCursor();
while(cursor.continue()) {
var value = cursor.value;
// act on each object or key
}
To start at the last record and end in the first record, the cursor
should be created with the direction parameter "prev".
ECMAScript
var cursor = store.openCursor("prev");
while(cursor.continue()) {
// act on each object or key
}
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.
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.
interface IDBCursorSync {
readonly attribute Object source;
readonly attribute DOMString direction;
readonly attribute any primaryKey;
IDBRequest update (any value);
boolean advance ([EnforceRange] unsigned long count);
boolean continue (optional any key);
boolean delete ();
};
Attributes
direction of type DOMString, readonly-
On getting, provide the traversal direction of the cursor.
No exceptions.
primaryKey of type any, readonly- Returns the cursor's current effective key.
Note that if this property returns an object (specifically an
Array), it returns the same
object instance every time it is inspected, until the cursor is iterated.
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.No exceptions.
source of type Object, readonly-
On getting, returns the
IDBObjectStoreSync or IDBIndexSync
which this cursor is iterating. This function
never returns null or throws an exception, even if the
cursor is currently being iterated, has iterated past its end,
or its transaction is not active.
No exceptions.
Methods
advance-
This method runs the steps for synchronously executing a request.
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. If the steps for synchronously
executing a request returns a cursor, then this function returns true. Otherwise
this function returns false.
Before this method returns, unless an exception was thrown, it sets the got value flag in 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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| count | unsigned long | ✘ | ✘ | The number of advances forward the cursor should make. |
| Exception | Description |
|---|
| DOMException | TypeError | The value passed into the count parameter was zero or a negative number. | TransactionInactiveError | The transaction this IDBCursorSync belongs to is not active. | InvalidStateError | The cursor is currently being iterated, or has iterated past its end. |
|
continue-
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 synchronously executing a request.
The steps are run with the cursor's source as source and the steps
for iterating a cursor as operation, using the cursor this is called on as cursor and
the key parameter as key. If the steps for synchronously executing a request returns
a cursor, then this function returns true. Otherwise this function returns false.
Before this method returns, unless an exception was thrown, it sets the got value flag in 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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| key | any | ✘ | ✔ | The next key to position this cursor at |
| Exception | Description |
|---|
| DOMException | TransactionInactiveError | The transaction this IDBCursorSync belongs to is not active. | InvalidStateError | The cursor is currently being iterated, or has iterated past its end. | DataError | The key parameter was specified but did not contain a valid key. |
|
delete-
This method throws a DOMException of type ReadOnlyError if the transaction which this IDBCursorSync 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 synchronously executing a request. The steps are run
with this IDBCursorSync 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. The function returns the
result of running these steps.
No parameters.
update-
This method throws a DOMException of type ReadOnlyError
if the transaction which this IDBCursorSync 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 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 synchronously executing a request and return the result returned by these steps.
The steps are run with this IDBCursorSync 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.
| Parameter | Type | Nullable | Optional | Description |
|---|
| value | any | ✘ | ✘ | The new value to store at the current position. |
interface IDBCursorWithValueSync : IDBCursorSync {
attribute any value;
};
Attributes
value of type any- Returns the cursor's current value.
Note that if this property returns an object, it returns the same
object instance every time it is inspected, until the cursor is iterated.
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.
No exceptions.
3.3.6 Transaction
When an application creates a
transaction synchronously, it blocks until the user agent is able
to reserve the required database objects.
interface IDBTransactionSync {
readonly attribute DOMString mode;
attribute IDBDatabaseSync db;
readonly attribute DOMError error;
IDBObjectStoreSync objectStore (DOMString name);
void abort ();
};
Attributes
db of type IDBDatabaseSync- The database connection of which this transaction
is a part
No exceptions.
error of type DOMError, readonly-
When the done flag is true, getting this
property must return the error of the request that caused the transaction to be aborted.
If the error was generated when committing the transaction and not from an individual request,
the error must contain the reasons for the transaction failure (e.g.
QuotaExceededError, UnknownError).
This is null when no error occurred or when the transaction is programmatically aborted.
When the done flag is false,
getting this property must throw a DOMException of type InvalidStateError.
| Exception | On Get | On Set | Description |
|---|
| DOMException | ✔ | ✘ | InvalidStateError | Thrown when this attribute was read when the done flag was set to false. |
|
mode of type DOMString, 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.
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.