Table of contents
- 1. About this document
- 2. Basic concepts
- 2.1. Best practices
- 2.2. Example
- 3. Method overview
- 4. Attributes
- 5. Constants
- 5.1. Mode constants
- 6. Event handlers
- 7. Methods
- 7.1. abort()
- 7.2. objectStore()
- 8. Known browser issues
- 9. Browser compatibility
The IDBTransaction
interface of the IndexedDB API provides a static, asynchronous transaction on a database using event handler attributes. All reading and writing of data are done within transactions. You actually use IDBDatabase
to start transactions and use IDBTransaction
to set the mode of the transaction and access an object store and make your request. You can also use it to abort transactions.
Inherits from: EventTarget
About this document
This document was last updated on December 1, 2011 and follows the W3C Specifications (Editor's Draft) drafted on October 18, 2011. It was last verified on October 24, 2011.
Basic concepts
The following are key concepts that you must understand when accessing data in IndexedDB:
- All reading and writing of data happens inside a transaction. Once you are inside the transaction, you can access the object stores that hold your data and make your requests.
- Transactions have three modes:
READ_ONLY
,READ_WRITE
, andVERSION_CHANGE
. - To change the "schema" or structure of the database—which involves creating or deleting object stores or indexes—the transaction must be in
VERSION_CHANGE
mode. This transaction can only be opened by calling thesetVersion()
method inIDBDatabse
. (In the latest specification, which has not yet been implemented by any browser, the method to call isIDBFactory.open()
.) - To make changes to an existing object store, the transaction can either be in
READ_ONLY
orREAD_WRITE
. You open such transactions with thetransaction()
method inIDBDatabse
. The method accepts two parameters: the scope (an array of object stores that you want to access) and the access type (READ_ONLY
orREAD_WRITE
) for the transaction. The method returns a transaction object containing theobjectStore()
method, which you can use to access your object store. By default, transactions open under the read-only mode.
To learn more about transactions, see Basic Concepts and IDBDatabase.
Best practices
You can speed up data access by using the right scope and mode in the transaction. Here's a couple of tips:
- When defining the scope, specify only the object stores you need. This way, you can run multiple transactions with non-overlapping scopes concurrently.
- Only specify a
READ_WRITE
transaction mode when necessary. You can concurrently run multipleREAD_ONLY
transactions with overlapping scopes, but you can have only oneREAD_WRITE
transaction for an object store. To learn more, see the definition for transactions in the Basic Concepts article.
Example
In the following code snippet, we open a transaction and add data to the object store. Because the specification is still evolving, Chrome uses prefixes in the methods. Chrome uses the webkit
prefix. For example, instead of just IDBTransaction.READ_WRITE
, use webkitIDBTransaction.READ_WRITE
. Firefox does not use prefixes, except in the opening method (mozIndexedDB
). Event handlers are registered for responding to various situations.
// Take care of the browser prefixes. if (window.indexedDb) { } else if (window.webkitIndexedDB) { window.indexedDB = window.webkitIndexedDB; window.IDBTransaction = window.webkitIDBTransaction; } else if (window.mozIndexedDB) { window.indexedDB = window.mozIndexedDB; } else { /* Browser not supported. */ } ... var idbReq = window.indexedDB.open('Database Name'); idbReq.onsuccess = function(event) { var db = this.result; var trans = db.transaction(['monster_store','hero_store'], IDBTransaction.READ_WRITE); var store = trans.objectStore('monster_store'); var req = store.put(value, key); req.onsuccess = ... req.onerror = ... }; idbReq.onerror = function(event) { ... };
Method overview
void abort() raises (IDBDatabaseException); |
IDBObjectStore objectStore (in DOMString name) raises (IDBDatabaseException); |
Attributes
Attribute | Type | Description |
---|---|---|
db | readonly IDBDatabase | The database connection that this transaction is associated with. |
mode | readonly unsigned short | The mode for isolating access to data in the object stores that are in the scope of the transaction. For possible values, see Constants. The default value is READ_ONLY . |
onabort | Function | The event handler for the onabort event. |
oncomplete | Function | The event handler for the oncomplete event. |
onerror | Function | The event handler for the error event. |
Constants
Mode constants
Transactions can have one of three modes:
Constant | Value | Description |
---|---|---|
READ_ONLY | 0 | Allows data to be read but not changed. |
READ_WRITE | 1 | Allows reading and writing of data in existing data stores to be changed. |
VERSION_CHANGE | 2 | Allows any operation to be performed, including ones that delete and create object stores and indexes. This mode is for updating the version number of transactions that were started using the setVersion() method of IDBDatabase objects. Transactions of this mode cannot run concurrently with other transactions. |
Event handlers
Object that implement this interface must support, as IDL attributes, the following event handlers and event handler types:
Event handler | Event handler type |
---|---|
onabort | abort |
oncomplete | complete |
onerror | error |
Methods
abort()
Returns immediately, and undoes all the changes to objects in the database associated with this transaction. If this transaction has been aborted or completed, then this method throws an error event, with its code set to ABORT_ERR
and a suitable message.
void abort( );
All pending IDBRequest
objects created during this transaction have their errorCode
set to ABORT_ERR
.
Exceptions
This method can raise an IDBDatabaseException, with the following code:
NOT_ALLOWED_ERR
- The transaction has already been committed or aborted.
objectStore()
Returns an object store that has already been added to the scope of this transaction. Every call to this method on the same transaction object, with the same name, returns the same IDBObjectStore instance. If this method is called on a different transaction object, a different IDBObjectStore instance is returned.
IDBObjectStore objectStore(
in DOMString name
) raises (IDBDatabaseException);
Parameters
- name
- The name of the requested object store.
Returns
IDBObjectStore
- An object for accessing the requested object store.
Exceptions
The method can raise an IDBDatabaseException with the following code:
NOT_FOUND_ERR
- The requested object store is not in this transaction's scope.
NOT_ALLOWED_ERR
- request is made on a source object that has been deleted or removed..
Known browser issues
Google Chrome currently serializes all transactions. So even if you have only read-only transactions and no read-write transaction, your transactions are executed one at a time. Any subsequent transactions are not executed until read-only transactions are completed. For the status, see bug 64076.