4.4. The IDBDatabase interface

The [IDBDatabase](#idbdatabase) interface represents a connection to a database.

An [IDBDatabase](#idbdatabase) object must not be garbage collected if its associated connection‘s close pending flag is unset and it has one or more event listeners registers whose type is one of abort, error, or versionchange. If an [IDBDatabase](#idbdatabase) object is garbage collected, the associated connection must be closed.

[Exposed=(Window,Worker)]
interface IDBDatabase : EventTarget {
  readonly attribute DOMString name;
  readonly attribute unsigned long long version;
  readonly attribute DOMStringList objectStoreNames;
 
  [NewObject] IDBTransaction transaction((DOMString or sequence<DOMString>) storeNames,
                                         optional IDBTransactionMode mode = "readonly");
  void close();
 
  [NewObject] IDBObjectStore createObjectStore(DOMString name,
                                               optional IDBObjectStoreParameters options);
  void deleteObjectStore(DOMString name);
 
  // Event handlers:
  attribute EventHandler onabort;
  attribute EventHandler onclose;
  attribute EventHandler onerror;
  attribute EventHandler onversionchange;
};
 
dictionary IDBObjectStoreParameters {
  (DOMString or sequence<DOMString>)? keyPath = null;
  boolean autoIncrement = false;
};

connection . [name](#dom-idbdatabase-name)

Returns the name of the database.

connection . [version](#dom-idbdatabase-version)

Returns the version of the database.

The name attribute’s getter must return the name of the connected database. The attribute must return this name even if the close pending flag is set on the connection. In other words, the value of this attribute stays constant for the lifetime of the [IDBDatabase](#idbdatabase) instance.

The version attribute’s getter must return this connection‘s version.

Is this the same as the database‘s version? As long as the connection is open, this is the same as the connected database‘s version. But once the connection has closed, this attribute will not reflect changes made with a later upgrade transaction.

connection . [objectStoreNames](#dom-idbdatabase-objectstorenames)

Returns a list of the names of object stores in the database.

store = connection . [createObjectStore](#dom-idbdatabase-createobjectstore)(name [, options])

Creates a new object store with the given name and options and returns a new [IDBObjectStore](#idbobjectstore).

Throws a “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) if not called within an upgrade transaction.

connection . [deleteObjectStore](#dom-idbdatabase-deleteobjectstore)(name)

Deletes the object store with the given name.

Throws a “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) if not called within an upgrade transaction.

The objectStoreNames attribute’s getter must return a [DOMStringList](https://www.w3.org/TR/html52/single-page.html#domstringlist) associated with a sorted name list of the names of the object stores in this connection‘s object store set.

Is this the same as the database‘s object store names? As long as the connection is open, this is the same as the connected database‘s object store names. But once the connection has closed, this attribute will not reflect changes made with a later upgrade transaction.

The createObjectStore(name, options) method, when invoked, must run these steps:

1. Let database be the database associated with this connection.

2. Let transaction be database’s upgrade transaction if it is not null, or throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) otherwise.

3. If transaction is not active, throw a “[TransactionInactiveError](https://www.w3.org/TR/WebIDL-1/#transactioninactiveerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

4. Let keyPath be options’s [keyPath](#dom-idbobjectstoreparameters-keypath) member if it is not undefined or null, or null otherwise.

5. If keyPath is not null and is not a valid key path, throw a “[SyntaxError](https://www.w3.org/TR/WebIDL-1/#syntaxerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

6. If an object store named name already exists in database throw a “[ConstraintError](https://www.w3.org/TR/WebIDL-1/#constrainterror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

7. Let autoIncrement be set if options’s [autoIncrement](#dom-idbobjectstoreparameters-autoincrement) member is true, or unset otherwise.

8. If autoIncrement is set and keyPath is an empty string or any sequence (empty or otherwise), throw an “[InvalidAccessError](https://www.w3.org/TR/WebIDL-1/#invalidaccesserror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

9. Let store be a new object store in database. Set the created object store‘s name to name. If autoIncrement is set, then the created object store uses a key generator. If keyPath is not null, set the created object store‘s key path to keyPath.

10. Return a new object store handle associated with store and transaction.

This method creates and returns a new object store with the given name in the connected database. Note that this method must only be called from within an upgrade transaction.

This method synchronously modifies the [objectStoreNames](#dom-idbdatabase-objectstorenames) property on the [IDBDatabase](#idbdatabase) instance on which it was called.

In some implementations it is possible for the implementation to run into problems after queuing a task to create the object store after the [createObjectStore()](#dom-idbdatabase-createobjectstore) method has returned. For example in implementations where metadata about the newly created object store 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](#idbobjectstore) object, and once the implementation determines that creating the object store has failed, it must abort the transaction using the steps to abort a transaction using the appropriate error. For example if creating the object store failed due to quota reasons, a “[QuotaExceededError](https://www.w3.org/TR/WebIDL-1/#quotaexceedederror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) must be used as error.

The deleteObjectStore(name) method, when invoked, must run these steps:

1. Let database be the database associated with this connection.

2. Let transaction be database’s upgrade transaction if it is not null, or throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) otherwise.

3. If transaction is not active, throw a “[TransactionInactiveError](https://www.w3.org/TR/WebIDL-1/#transactioninactiveerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

4. Let store be the object store named name in database, or throw a “[NotFoundError](https://www.w3.org/TR/WebIDL-1/#notfounderror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) if none.

5. Remove store from this connection‘s object store set.

6. If there is an object store handle associated with store and transaction, remove all entries from its index set.

7. Destroy store.

This method destroys the object store with the given name in the connected database. Note that this method must only be called from within an upgrade transaction.

This method synchronously modifies the [objectStoreNames](#dom-idbdatabase-objectstorenames) property on the [IDBDatabase](#idbdatabase) instance on which it was called.

transaction = connection . [transaction](#dom-idbdatabase-transaction)(scope [, mode = “readonly”])

Returns a new transaction with the given mode (["readonly"](#dom-idbtransactionmode-readonly) or ["readwrite"](#dom-idbtransactionmode-readwrite)) and scope which can be a single object store name or an array of names.

connection . [close](#dom-idbdatabase-close)()

Closes the connection once all running transactions have finished.

The transaction(storeNames, mode) method, when invoked, must run these steps:

1. If a running upgrade transaction is associated with the connection, throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

2. If the connection‘s close pending flag is set, throw an “[InvalidStateError](https://www.w3.org/TR/WebIDL-1/#invalidstateerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

3. Let scope be the set of unique strings in storeNames if it is a sequence, or a set containing one string equal to storeNames otherwise.

4. If any string in scope is not the name of an object store in the connected database, throw a “[NotFoundError](https://www.w3.org/TR/WebIDL-1/#notfounderror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

5. If scope is empty, throw an “[InvalidAccessError](https://www.w3.org/TR/WebIDL-1/#invalidaccesserror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

6. If mode is not ["readonly"](#dom-idbtransactionmode-readonly) or ["readwrite"](#dom-idbtransactionmode-readwrite), throw a TypeError.

7. Let transaction be a newly created transaction with connection, mode and the set of object stores named in scope.

8. Set transaction’s cleanup event loop to the current event loop.

9. Return an [IDBTransaction](#idbtransaction) object representing transaction.

The created transaction will follow the lifetime rules.

The close() method, when invoked, must run these steps:

1. Run the steps to close a database connection with this connection.

The onabort attribute is the event handler for the abort event.

The onclose attribute is the event handler for the close event.

🚧 The [onclose](#dom-idbdatabase-onclose) attribute is new in this edition. It is supported in Chrome 31, Firefox 50, and Safari 10.1. 🚧

The onerror attribute is the event handler for the error event.

The onversionchange attribute is the event handler for the versionchange event.