HTML5 Databases 详解

4.1 Databases

Each origin has an associated set of databases. Each database has a name and a current version. There is no way to enumerate or delete the databases available for an origin from this API.

Each database has one version at a time; a database can't exist in multiple versions at once. Versions are intended to allow authors to manage schema changes incrementally and non-destructively, and without running the risk of old code (e.g. in another browser window) trying to write to a database with incorrect assumptions.

[Supplemental, NoInterfaceObject]
interface WindowDatabase {
  Database openDatabase(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize, in optional DatabaseCallback creationCallback);
};
Window implements WindowDatabase;

[Supplemental, NoInterfaceObject]
interface WorkerUtilsDatabase {
  Database openDatabase(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize, in optional DatabaseCallback creationCallback);
  DatabaseSync openDatabaseSync(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize, in optional DatabaseCallback creationCallback);
};
WorkerUtils implements WorkerUtilsDatabase;

[Callback=FunctionOnly, NoInterfaceObject]
interface DatabaseCallback {
  void handleEvent(in Database database);
};

The openDatabase() method on the Window and WorkerUtils interfaces and the openDatabaseSync() method on the WorkerUtils interface take the following arguments: a database name, a database version, a display name, an estimated size — in bytes — of the data that will be stored in the database, and optionally a callback to be invoked if the database has not yet been created. The callback, if provided, is intended to be used to call changeVersion(); the callback is invoked with the database having the empty string as its version regardless of the given database version. If the callback is not provided, the database is created with the given database version as its version.

When invoked, these methods must run the following steps, with all but the last two steps being run atomically:

1. The user agent may raise a SECURITY_ERR exception instead of returning a Database object if the request violates a policy decision (e.g. if the user agent is configured to not allow the page to open databases).

2. For the method on the Window object: let origin be the origin of the active document of the browsing context of the Window object on which the method was invoked.

   For the methods on the WorkerUtils object: let origin be the origin of the scripts in the worker.

3. If origin is not a scheme/host/port tuple, then throw a SECURITY_ERR exception and abort these steps.

4. If the database version provided is not the empty string, and there is already a database with the given name from the origin origin, but the database has a different version than the version provided, then throw an INVALID_STATE_ERR exception and abort these steps.

5. If no database with the given name from the origin origin exists, then create the database and let created be true. If a callback was passed to the method, then set the new database's version to the empty string. Otherwise, set the new database's version to the given database version.

   Otherwise, if a database with the given name already exists, let created be false.

6. For the openDatabase() methods: let result be a newly constructed Database object representing the database with the given database name from the originorigin.

   For the openDatabaseSync() method: let result be a newly constructed DatabaseSync object representing the database with the given database name from the origin origin.

7. If created is false or if no callback was passed to the method, skip this step. Otherwise:

   For the openDatabase() methods: queue a task to to invoke the callback with result as its only argument.

   For the openDatabaseSync() method: invoke the callback with result as its only argument. If the callback throws an exception, rethrow that exception and abort these steps.

8. Return result.

All strings including the empty string are valid database names. Database names must be compared in a case-sensitive manner.

Implementations can support this even in environments that only support a subset of all strings as database names by mapping database names (e.g. using a hashing algorithm) to the supported set of names.

The version that the database was opened with is the expected version of this Database or DatabaseSync object. It can be the empty string, in which case there is no expected version — any version is fine.

User agents are expected to use the display name and the estimated database size to optimize the user experience. For example, a user agent could use the estimated size to suggest an initial quota to the user. This allows a site that is aware that it will try to use hundreds of megabytes to declare this upfront, instead of the user agent prompting the user for permission to increase the quota every five megabytes.