IDBTransaction

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, and VERSION_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 the setVersion() method in IDBDatabse. (In the latest specification, which has not yet been implemented by any browser, the method to call is IDBFactory.open().)
  • To make changes to an existing object store, the transaction can either be in READ_ONLY or READ_WRITE. You open such transactions with the transaction() method in IDBDatabse. The method accepts two parameters: the scope (an array of object stores that you want to access) and the access type (READ_ONLY or READ_WRITE) for the transaction. The method returns a transaction object containing the objectStore() 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 multiple READ_ONLY transactions with overlapping scopes, but you can have only one READ_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_WRITEFirefox 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.   

Browser compatibility

  • Desktop
  • Mobile

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 12 -webkit 4.0 (2.0) -- -- --
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support -- 6.0 (6.0) ? -- --

Tags (0)

Edit tags
  • No tags

Attachments (0)

 

Attach file