4.3. The IDBFactory interface

Database objects are accessed through methods on the [IDBFactory](#idbfactory) interface. A single object implementing this interface is present in the global scope of environments that support Indexed DB operations.

partial interface mixin WindowOrWorkerGlobalScope {
  [SameObject] readonly attribute IDBFactory indexedDB;
};

The indexedDB attribute provides applications a mechanism for accessing capabilities of indexed databases.

[Exposed=(Window,Worker)]
interface IDBFactory {
  [NewObject] IDBOpenDBRequest open(DOMString name,
                                    optional [EnforceRange] unsigned long long version);
  [NewObject] IDBOpenDBRequest deleteDatabase(DOMString name);
 
  Promise<sequence<IDBDatabaseInfo>> databases();
 
  short cmp(any first, any second);
};
 
dictionary IDBDatabaseInfo {
  DOMString name;
  unsigned long long version;
};

request = indexedDB . [open](#dom-idbfactory-open)(name)

Attempts to open a connection to the named database with the current version, or 1 if it does not already exist. If the request is successful request’s [result](#dom-idbrequest-result) will be the connection.

request = indexedDB . [open](#dom-idbfactory-open)(name, version)

Attempts to open a connection to the named database with the specified version. If the database already exists with a lower version and there are open connections that don’t close in response to a versionchange event, the request will be blocked until they all close, then an upgrade will occur. If the database already exists with a higher version the request will fail. If the request is successful request’s [result](#dom-idbrequest-result) will be the connection.

request = indexedDB . [deleteDatabase](#dom-idbfactory-deletedatabase)(name)

Attempts to delete the named database. If the database already exists and there are open connections that don’t close in response to a versionchange event, the request will be blocked until they all close. If the request is successful request’s [result](#dom-idbrequest-result) will be null.

result = await indexedDB . [databases](#dom-idbfactory-databases)()

Returns a promise which resolves to a list of objects giving a snapshot of the names and versions of databases within the origin.

This API is intended for web applications to introspect the use of databases, for example to clean up from earlier versions of a site’s code. Note that the result is a snapshot; there are no guarantees about the sequencing of the collection of the data or the delivery of the response with respect to requests to create, upgrade, or delete databases by this context or others.

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

1. If version is 0 (zero), throw a TypeError.

2. Let environment be this‘s relevant settings object.

3. Let origin be environment’s origin.

4. If origin is an opaque origin, throw a “[SecurityError](https://heycam.github.io/webidl/#securityerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException) and abort these steps.

5. Let request be a new open request.

6. Run these steps in parallel:

   1. Let result be the result of running open a database, with origin, name, version if given and undefined otherwise, and request.

      What happens if version is not given? If version is not given and a database with that name already exists, a connection will be opened without changing the version. If version is not given and no database with that name exists, a new database will be created with version equal to 1.

   2. Queue a task to run these steps:

      1. If result is an error, then:

         1. Set request’s result to undefined.

         2. Set request’s error to result.

         3. Set request’s done flag to true.

         4. Fire an event named error at request with its [bubbles](https://dom.spec.whatwg.org/#dom-event-bubbles) and [cancelable](https://dom.spec.whatwg.org/#dom-event-cancelable) attributes initialized to true.

      2. Otherwise:

         1. Set request’s result to result.

         2. Set request’s done flag to true.

         3. Fire an event named success at request.

        If the steps above resulted in an [upgrade transaction](#upgrade-transaction) being run, these steps will run after that transaction finishes. This ensures that in the case where another version upgrade is about to happen, the success event is fired on the connection first so that the script gets a chance to register a listener for the [`versionchange`](#eventdef-connection-versionchange) event.
        Why aren’t the steps to [fire a success event](#fire-a-success-event) or [fire an error event](#fire-an-error-event) used? There is no transaction associated with the request (at this point), so those steps — which activate an associated transaction before dispatch and deactivate the transaction after dispatch — do not apply.

1. Return a new [IDBOpenDBRequest](#idbopendbrequest) object for request.

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

1. Let environment be this‘s relevant settings object.

2. Let origin be environment’s origin.

3. If origin is an opaque origin, throw a “[SecurityError](https://heycam.github.io/webidl/#securityerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException) and abort these steps.

4. Let request be a new open request.

5. Run these steps in parallel:

   1. Let result be the result of running delete a database, with origin, name, and request.

   2. Set request’s processed flag to true.

   3. Queue a task to run these steps:

      1. If result is an error, set request’s error to result, set request’s done flag to true, and fire an event named error at request with its [bubbles](https://dom.spec.whatwg.org/#dom-event-bubbles) and [cancelable](https://dom.spec.whatwg.org/#dom-event-cancelable) attributes initialized to true.

      2. Otherwise, set request’s result to undefined, set request’s done flag to true, and fire a version change event named success at request with result and null.

         Why aren’t the steps to fire a success event or fire an error event used? There is no transaction associated with the request, so those steps — which activate an associated transaction before dispatch and deactivate the transaction after dispatch — do not apply.

         Also, the success event here is a [IDBVersionChangeEvent](#idbversionchangeevent) which includes the [oldVersion](#dom-idbversionchangeevent-oldversion) and [newVersion](#dom-idbversionchangeevent-newversion) details.

6. Return a new [IDBOpenDBRequest](#idbopendbrequest) object for request.

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

1. Let environment be this‘s relevant settings object.

2. Let origin be environment’s origin.

3. If origin is an opaque origin, then return a promise rejected with a “[SecurityError](https://heycam.github.io/webidl/#securityerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

4. Let p be a new promise.

5. Run these steps in parallel:

   1. Let databases be the set of databases in origin. If this cannot be determined for any reason, then reject p with an appropriate error (e.g. an “[UnknownError](https://heycam.github.io/webidl/#unknownerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException)) and terminate these steps.

   2. Let result be a new list.

   3. For each db of databases:

      1. Let info be a new [IDBDatabaseInfo](#dictdef-idbdatabaseinfo) dictionary.

      2. Set info’s [name](#dom-idbdatabaseinfo-name) dictionary member to db’s name.

      3. Set info’s [version](#dom-idbdatabaseinfo-version) dictionary member to db’s version.

      4. Append info to result.

   4. Resolve p with result.

6. Return p.

🚧 The [databases()](#dom-idbfactory-databases) method is new in this edition. It is supported in Chrome 71 and Edge 79. 🚧

result = indexedDB . [cmp](#dom-idbfactory-cmp)(key1, key2)

Compares two values as keys. Returns -1 if key1 precedes key2, 1 if key2 precedes key1, and 0 if the keys are equal.

Throws a “[DataError](https://heycam.github.io/webidl/#dataerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException) if either input is not a valid key.

The cmp(first, second) method, when invoked, must run these steps:

1. Let a be the result of running convert a value to a key with first. Rethrow any exceptions.

2. If a is invalid, throw a “[DataError](https://heycam.github.io/webidl/#dataerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

3. Let b be the result of running convert a value to a key with second. Rethrow any exceptions.

4. If b is invalid, throw a “[DataError](https://heycam.github.io/webidl/#dataerror)“ [DOMException](https://heycam.github.io/webidl/#idl-DOMException).

5. Return the results of running compare two keys with a and b.