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 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);
 
  short cmp(any first, any second);
};

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 all they 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 all they close. If the request is successful request’s [result](#dom-idbrequest-result) will be null.

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

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

2. Let origin be the origin of the global scope used to access this [IDBFactory](#idbfactory).

3. If origin is an opaque origin, throw a “[SecurityError](https://www.w3.org/TR/WebIDL-1/#securityerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#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 the steps to 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, set request’s result to undefined, set request’s error to result, set request’s done flag, and fire an event named error at request with its [bubbles](https://www.w3.org/TR/dom41/#dom-event-bubbles) and [cancelable](https://www.w3.org/TR/dom41/#dom-event-cancelable) attributes initialized to true.

      2. Otherwise, set request’s result to result, set request’s done flag, and fire an event named success at request. If the steps above resulted in an upgrade transaction being run, then firing the “success“ event must be done after the upgrade transaction completes.

         The last requirement is to ensure that in case 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 event.

         Why aren’t the steps to fire a success event or 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.

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

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

1. Let origin be the origin of the global scope used to access this [IDBFactory](#idbfactory).

2. If origin is an opaque origin, throw a “[SecurityError](https://www.w3.org/TR/WebIDL-1/#securityerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException) and abort these steps.

3. Let request be a new open request.

4. Run these steps in parallel:

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

   2. Queue a task to run these steps:

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

      2. Otherwise, set request’s result to undefined, set request’s done flag, 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.

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

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://www.w3.org/TR/WebIDL-1/#dataerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#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 the steps to convert a value to a key with first. Rethrow any exceptions.

2. If a is invalid, throw a “[DataError](https://www.w3.org/TR/WebIDL-1/#dataerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

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

4. If b is invalid, throw a “[DataError](https://www.w3.org/TR/WebIDL-1/#dataerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

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