4. API - 4.4. The IDBDatabase interface - 《Indexed Database API 3.0》

4.4. The IDBDatabase interface

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 false 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",
                                         optional IDBTransactionOptions options = {});
  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;
};
 
enum IDBTransactionDurability { "default", "strict", "relaxed" };
 
dictionary IDBTransactionOptions {
  IDBTransactionDurability durability = "default";
};
 
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 this‘s associated database‘s name. The attribute must return this name even if this‘s close pending flag is true. 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‘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://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException) if not called within an upgrade transaction.

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

Deletes the object store with the given name.

The objectStoreNames attribute’s getter must return a [DOMStringList](https://html.spec.whatwg.org/multipage/common-dom-interfaces.html#domstringlist) associated with a sorted name list of the names of the object stores in this‘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:

Let database be this‘s associated database.
Let transaction be database’s upgrade transaction if it is not null, or throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException) otherwise.
If transaction’s state is not active, then throw a “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).
Let keyPath be options’s [keyPath](#dom-idbobjectstoreparameters-keypath) member if it is not undefined or null, or null otherwise.
If keyPath is not null and is not a valid key path, throw a “[SyntaxError](https://heycam.github.io/webidl/#syntaxerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).
If an object store named name already exists in database throw a “[ConstraintError](https://heycam.github.io/webidl/#constrainterror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).
Let autoIncrement be options’s [autoIncrement](#dom-idbobjectstoreparameters-autoincrement) member.
If autoIncrement is true and keyPath is an empty string or any sequence (empty or otherwise), throw an “[InvalidAccessError](https://heycam.github.io/webidl/#invalidaccesserror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).
Let store be a new object store in database. Set the created object store‘s name to name. If autoIncrement is true, then the created object store uses a key generator. If keyPath is not null, set the created object store‘s key path to keyPath.
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://heycam.github.io/webidl/#quotaexceedederror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException) must be used as error.

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

Let database be this‘s associated database.
Let transaction be database’s upgrade transaction if it is not null, or throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException) otherwise.
If transaction’s state is not active, then throw a “[TransactionInactiveError](https://heycam.github.io/webidl/#transactioninactiveerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).
Let store be the object store named name in database, or throw a “[NotFoundError](https://heycam.github.io/webidl/#notfounderror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException) if none.
Remove store from this‘s object store set.
If there is an object store handle associated with store and transaction, remove all entries from its index set.
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 [, options ] ])

Returns a new transaction with the given scope (which can be a single object store name or an array of names), mode (["readonly"](#dom-idbtransactionmode-readonly) or ["readwrite"](#dom-idbtransactionmode-readwrite)), and additional options including [durability](#dom-idbtransactionoptions-durability) (["default"](#dom-idbtransactiondurability-default), ["strict"](#dom-idbtransactiondurability-strict) or ["relaxed"](#dom-idbtransactiondurability-relaxed)).

The default mode is ["readonly"](#dom-idbtransactionmode-readonly) and the default [durability](#dom-idbtransactionoptions-durability) is ["default"](#dom-idbtransactiondurability-default).

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

Closes the connection once all running transactions have finished.

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

If a running upgrade transaction is associated with the connection, throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).
If this‘s close pending flag is true, then throw an “[InvalidStateError](https://heycam.github.io/webidl/#invalidstateerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).
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.
If any string in scope is not the name of an object store in the connected database, throw a “[NotFoundError](https://heycam.github.io/webidl/#notfounderror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).
If scope is empty, throw an “[InvalidAccessError](https://heycam.github.io/webidl/#invalidaccesserror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).
If mode is not ["readonly"](#dom-idbtransactionmode-readonly) or ["readwrite"](#dom-idbtransactionmode-readwrite), throw a TypeError.
Let transaction be a newly created transaction with connection, mode, options’ [durability](#dom-idbtransactionoptions-durability) member, and the set of object stores named in scope.
Set transaction’s cleanup event loop to the current event loop.
Return an [IDBTransaction](#idbtransaction) object representing transaction.

🚧 The [durability](#dom-idbtransactionoptions-durability) option is new in this edition. It is supported in Chrome 82 and Edge 82. 🚧

The created transaction will follow the lifetime rules.

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

Run close a database connection with this connection.

The connection will not actually close until all outstanding transactions have completed. Subsequent calls to [close()](#dom-idbdatabase-close) will have no effect.

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

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

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

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