IDBDatabase Interface
The IDBDatabase
interface of the IndexedDB API provides asynchronous access to a connection to a database. Use it to create, manipulate, and delete objects in that database. The interface also provides the only way to get a transaction and manage versions on that database.
Inherits from: EventTarget
Extends
Methods
Code void close() #
Returns immediately and closes the connection in a separate thread. The connection is not actually closed until all transactions created using this connection are complete. No new transactions can be created for this connection once this method is called. Methods that create transactions throw an exception if a closing operation is pending.
void close();
void close();
Code IDBObjectStore createObjectStore(String name, [Map options]) #
Creates and returns a new object store or index. The method takes the name of the store as well as a parameter object. The parameter object lets you define important optional properties. You can use the property to uniquely identify individual objects in the store. As the property is an identifier, it should be unique to every object, and every object should have that property.
But before you can create any object store or index, you must first call the setVersion()
method.
Parameters
- name
- The name of the new object store.
- optionalParameters
- Warning: The latest draft of the specification changed this to
IDBDatabaseOptionalParameters
, which is not yet recognized by any browserOptional. Options object whose attributes are optional parameters to the method. It includes the following properties:
Attribute Description keyPath
The key path to be used by the new object store. If empty or not specified, the object store is created without a key path and uses out-of-line keys. autoIncrement
If true, the object store has a key generator. Defaults to false
.Unknown parameters are ignored.
Returns
IDBObjectStore
- The newly created object store.
Exceptions
This method can raise an IDBDatabaseException with the following codes:
Exception | Description |
---|---|
NOT_ALLOWED_ERR | The method was not called from a VERSION_CHANGE transaction callback. You must call setVersion() first. |
CONSTRAINT_ERR | An object store with the given name (based on case-sensitive comparison) already exists in the connected database. |
NON_TRANSIENT_ERR | optionalParameters has attributes other than keyPath and autoIncrement . |
IDBObjectStore createObjectStore(String name, [Map options]);
Code void deleteObjectStore(String name) #
Destroys the object store with the given name in the connected database, along with any indexes that reference it.
As with createObjectStore()
, this method can be called only within a VERSION_CHANGE
transaction. So you must call the setVersion()
method first before you can remove any object store or index.
Parameters
- name
- The name of the data store to delete.
Returns
void
Exceptions
This method can raise an IDBDatabaseException with the following codes:
Exception | Description |
---|---|
NOT_ALLOWED_ERR | The method was not called from a VERSION_CHANGE transaction callback. You must call setVersion() first. |
NOT_FOUND_ERR | You are trying to delete an object store that does not exist. Names are case sensitive. |
void deleteObjectStore(String name);
Code IDBDatabaseEvents get on() #
IDBDatabaseEvents get on();
Code IDBVersionChangeRequest setVersion(String version) #
IDBDatabase.open()
method and to create and delete object stores in the onupdateneeded
event handler associated to the returned request.Updates the version of the database. Returns immediately and runs a VERSION_CHANGE
transaction on the connected database in a separate thread.
Call this method before creating or deleting an object store.
Parameters
- version
- The version to store in the database.
Returns
IDBVersionChangeRequest
- The request to change the version of a database.
IDBVersionChangeRequest setVersion(String version);
Code IDBTransaction transaction(storeName_OR_storeNames, String mode) #
Immediately returns an IDBTransaction object, and starts a transaction in a separate thread. The method returns a transaction object (IDBTransaction
) containing the objectStore() method, which you can use to access your object store.
Parameters
- storeNames
- The names of object stores and indexes that are in the scope of the new transaction. Specify only the object stores that you need to access.
- mode
- Optional. The types of access that can be performed in the transaction. Transactions are opened in one of three modes:
READ_ONLY
,READ_WRITE
, andVERSION_CHANGE
. If you don't provide the parameter, the default access mode isREAD_ONLY
. To avoid slowing things down, don't open aREAD_WRITE
transaction, unless you actually need to write into the database.
Sample code
To start a transaction with the following scope, you can use the code snippets in the table. As noted earlier:
- Add prefixes to the methods in WebKit browsers, (that is, instead of
IDBTransaction.READ_ONLY
, usewebkitIDBTransaction.READ_ONLY
). - The default mode is
READ_ONLY
, so you don't really have to specify it. Of course, if you need to write into the object store, you can open the transaction in theREAD_WRITE
mode.
Scope | Code |
---|---|
Single object store |
Alternatively:
|
Multiple object stores | var transaction = db.transaction(['my-store-name', 'my-store-name2'], IDBTransaction.READ_ONLY); |
All object stores |
You cannot pass an empty array into the storeNames parameter, such as in the following: Warning: Accessing all obejct stores under the READ_WRITE mode means that you can run only that transaction. You cannot have writing transactions with overlapping scopes. |
Returns
IDBTransaction
- The transaction object.
Exceptions
This method can raise an IDBDatabaseException with the following codes:
Exception | Description |
---|---|
NOT_ALLOWED_ERR | The error is thrown for one of two reasons:
|
NOT_FOUND_ERR | One of the object stores doesn't exist in the connected database. |
IDBTransaction transaction(storeName_OR_storeNames, String mode);
Code void $dom_addEventListener(String type, EventListener listener, [bool useCapture]) #
void $dom_addEventListener(String type, EventListener listener, [bool useCapture]);
Code void $dom_removeEventListener(String type, EventListener listener, [bool useCapture]) #
void $dom_removeEventListener(String type, EventListener listener, [bool useCapture]);
Fields
Code final List<String> objectStoreNames #
final List<String> objectStoreNames;
Code final version #
final Dynamic version;
This page includes content from the Mozilla Foundation that is graciously licensed under a Creative Commons: Attribution-Sharealike license. Mozilla has no other association with Dart or dartlang.org. We encourage you to improve the web by contributing to The Mozilla Developer Network.