Web Database
- - -Editor's Draft 29 August 2009
- -- Latest Editor's Draft: -
- http://dev.w3.org/html5/webdatabase/ -
- Previous Versions: -
- http://www.w3.org/TR/2009/WD-webdatabase-20090423/
- :ZZZ -->
+
- http://www.w3.org/TR/2009/WD-webstorage-20090423/ +
- http://www.w3.org/TR/2009/WD-webdatabase-20091029/
+ - http://www.w3.org/TR/2009/WD-webstorage-20090423/ +
- Editors:
- Ian Hickson, Google, Inc.
Copyright - © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C @@ -197,8 +204,10 @@ trademark and document use rules apply.
+ +Abstract
This specification defines an API for storing data in databases - that can be queried using a variant of SQL.
Status of this document
This section describes the status of this document at the
+ that can be queried using a variant of SQL. This section describes the status of this document at the
time of its publication. Other documents may supersede this
document. A list of current W3C publications and the most recently
formally published revision of this technical report can be found in
@@ -213,7 +222,7 @@
archives),
- or submit them using our
+ or submit them using our
public bug database.
All feedback is welcome. Implementors should be aware that this specification is not
@@ -222,7 +231,16 @@
under them in incompatible ways. Vendors interested in
implementing this specification before it eventually reaches the
Candidate Recommendation stage should join the aforementioned
- mailing lists and take part in the discussions. The latest stable version of the editor's draft of this
+ mailing lists and take part in the discussions. This specification has reached an impasse: all
+ interested implementors have used the same SQL backend (Sqlite), but
+ we need multiple independent implementations to proceed along a
+ standardisation path. Until another implementor is interested in
+ implementing this spec, the description of the SQL dialect has been
+ left as simply a reference to Sqlite, which isn't acceptable for a
+ standard. Should you be an implementor interested in implementing an
+ independent SQL backend, please contact the editor so that he can
+ write a specification for the dialect, thus allowing this
+ specification to move forward. The latest stable version of the editor's draft of this
specification is always available on the W3C CVS
server. Change tracking for this document is available at the
following location: The W3C Web Apps
+ The W3C Web Applications
Working Group is the W3C working group responsible for this
specification's progress along the W3C Recommendation track.
-
-
- This specification is the 29 August 2009 Editor's Draft.
-
+ This specification is the 9 August 2010 Editor's Draft.
This document was produced by a group operating under the 5
February 2004 W3C Patent Policy. W3C maintains a public list of
any patent disclosures made in connection with the deliverables
@@ -249,7 +264,7 @@
patent. An individual who has actual knowledge of a patent which the
individual believes contains Essential
Claim(s) must disclose the information in accordance with section
- 6 of the W3C Patent Policy. User agents may impose implementation-specific limits on
otherwise unconstrained inputs, e.g. to prevent denial of service
attacks, to guard against running out of memory, or to work around
- platform-specific limitations. This specification relies on several other underlying
- specifications. When support for a feature is disabled (e.g. as an emergency
+ measure to mitigate a security problem, or to aid in development, or
+ for performance reasons), user agents must act as if they had no
+ support for the feature whatsoever, and as if the feature was not
+ mentioned in this specification. For example, if a particular
+ feature is accessed via an attribute in a Web IDL interface, the
+ attribute itself would be omitted from the objects that implement
+ that interface — leaving the attribute on the object but
+ making it return null or throw an exception is insufficient. This specification relies on several other underlying
+ specifications. Many fundamental concepts from HTML5 are used by this
- specification. [HTML5] Many fundamental concepts from HTML are used by this
+ specification. [HTML] A DOM attribute is said to be getting when its value is
+ specifications. [DOMCORE] An IDL attribute is said to be getting when its value is
being retrieved (e.g. by author script), and is said to be
setting when a new value is assigned to it. The term "JavaScript" is used to refer to ECMA262, rather than
the official term ECMAScript, since the term JavaScript is more
@@ -451,6 +473,10 @@ interface Dat
If origin is not a scheme/host/port
+ tuple, then throw a 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
@@ -461,11 +487,13 @@ interface Dat
If no database with the given name from the origin origin exists, then create the database and let
- created be true. Otherwise, let created be false. If a callback was passed to the method, then let the database's
- version be the empty string. Otherwise, let its version be the
- given database version Otherwise, if a database with the given name already exists,
+ let created be false. When the user agent is to preprocess a SQL statement sqlStatement with an array of arguments arguments, it must run the following steps: Parse sqlStatement as a SQL statement,
- with the exception that U+003F QUESTION MARK (?) characters can be
+ with the exception that U+003F QUESTION MARK characters (?) can be
used in place of SQL literals in the statement. [SQL] Replace each Substitutions for Bind each Binding the The result is the statement. A future version of this specification will probably
define the exact SQL subset required in more detail. ...and the mode being read/write. The ...and the mode being read/write. If any of the optional arguments are omitted, then they must be
+ treated as if they were null. The Queue a task to invoke the transaction
- callback with the aforementioned If the transaction callback is not null, queue
+ a task to invoke the transaction callback with the
+ aforementioned If the callback couldn't be called (e.g. it was null), or if
- the callback was invoked and raised an exception, jump to the last
+ If the callback raised an exception, jump to the last
step. While there are any statements queued up in the transaction,
perform the following steps for each queued up statement in the
transaction, oldest first. Each statement has a statement,
@@ -746,11 +770,11 @@ interface SQLResultSet object that represents
the result of the statement. If the statement has a result set callback, queue a
- task to invoke it with the If the statement has a result set callback that is not
+ null, queue a task to invoke it with the
+ If the callback was invoked and raised an exception, jump
to the last step in the overall steps. If the statement had an associated error callback, then
- queue a task to invoke that error callback with the
- If the statement had an associated error callback that is
+ not null, then queue a task to invoke that error
+ callback with the If the error callback returns false, then move on to the
@@ -783,36 +807,35 @@ interface changeVersion()
+ the transaction and, if that succeeds, run the postflight
+ operation. If the commit fails, then instead jump to the last
+ step. (This is basically a hook for the Otherwise: commit the transaction and run the postflight
- operation. If an error occurred in the committing of the
- transaction, jump to the last step. Otherwise: commit the transaction. If an error occurred in the
+ committing of the transaction, jump to the last step. Queue a task to invoke the success
- callback. End these steps. The next step is only used when something
goes wrong. Queue a task to invoke the error
- callback with a newly constructed Queue a task to invoke the transaction's
+ error callback, if it is not null, with a newly constructed
+ The task source for these tasks is the database
- access task source. The task source for these tasks is the database access task
+ source. If the third argument is null, rollback the transaction,
- throw a Invoke the callback given by the third argument, passing it
- the transaction object as its only
- argument. If the third argument is not null, invoke the callback given
+ by the third argument, passing it the transaction object as its only argument. Mark the The A When the If the The Implementors are encouraged to implement
- For the asynchronous API, implementors are
+ encouraged to prefetch all the data for
+ Fetching the The The The Errors in the synchronous database API are reported using
The The The The error codes are as follows: Need to define the SQL dialect. User agents should limit the total amount of space allowed for
+ User agents must implement the SQL dialect supported by Sqlite 3.6.19. When converting bound arguments to SQL data types, the JavaScript
+ ToPrimitive abstract operation must be applied to obtain the raw
+ value to be processed. [ECMA262]. User agents should limit the total amount of space allowed for
databases.
User agents should guard against sites storing data under the
@@ -1101,7 +1125,8 @@ interface S
future. A third-party advertiser (or any entity capable of getting
content distributed to multiple sites) could use a unique identifier
stored in its
- client-side database
+ client-side databases
+
to track a user across multiple sessions, building a profile of the
user's interests to allow for highly targeted advertising. In
@@ -1116,6 +1141,7 @@ interface S
User agents may restrict access to
the database objects
+
to scripts originating at the domain of the top-level document of
the browsing context, for instance denying access to
the API for pages from other domains running in
@@ -1126,8 +1152,8 @@ interface S
User agents may automatically delete stored data after a period
- of time. User agents may, if so configured by the user, automatically
+ delete stored data after a period of time. This can restrict the ability of a site to track a user, as the
@@ -1135,36 +1161,40 @@ interface S
sessions when he authenticates with the site itself (e.g. by
making a purchase or logging in to a service). However, this also puts the user's data at risk. However, this also reduces the usefulness of the API as a
+ long-term storage mechanism. It can also put the user's data at
+ risk, if the user does not fully understand the implications of
+ data expiration. User agents should present the
- database feature
+ If users attempt to protect their privacy by clearing cookies
+ without also clearing data stored in the
+ relevant databases,
- to the user in a way that does not distinguish them from HTTP
- session cookies. [RFC2109] [COOKIES] This might encourage users to view such storage with healthy
- suspicion. User agents may require the user to authorize access to
databases before a site can use the feature. If the user interface for persistent storage presents data in the
- persistent storage features described in this specification
- separately from data in HTTP session cookies, then users are likely
- to delete data in one and not the other. This would allow sites to
- use the two features as redundant backup for each other, defeating a
- user's attempts to protect his privacy. User agents should treat persistently stored data as potentially
+ separate sessions into coherent user profiles. User agents should treat persistently stored data as potentially
sensitive; it's quite possible for e-mails, calendar appointments,
health records, or other confidential documents to be stored in this
mechanism. To this end, user agents should ensure that when deleting data,
- it is promptly deleted from the underlying storage. Because of the potential for DNS spoofing attacks, one cannot
+ it is promptly deleted from the underlying storage. Because of the potential for DNS spoofing attacks, one cannot
guarantee that a host claiming to be in a certain domain really is
- from that domain. To mitigate this, pages can use SSL. Pages using
- SSL can be sure that only pages using SSL that have certificates
+ from that domain. To mitigate this, pages can use TLS. Pages using
+ TLS can be sure that only pages using TLS that have certificates
identifying them as being from the same domain can access their
databases.
@@ -1257,46 +1282,37 @@ interface S
there is little reason to allow Web authors to control the character
encoding used in the disk representation of the data, as all data in
JavaScript is implicitly UTF-16. Authors are strongly recommended to make use of the All references are normative unless marked "Non-normative". All references are normative unless marked "Non-normative".Status of This document
Table of contents
+ 6 of the W3C Patent Policy.Table of Contents
+
2.1 Dependencies
2.1 Dependencies
Document object or of any other
Node objects as defined in the DOM Core
- specifications. [DOMCORE]SECURITY_ERR exception and abort
+ these steps.4.2 Parsing and processing SQL statements
? placeholder with the value
- of the argument in the arguments array with
- the same position. (So the first ?
- placeholder gets replaced by the first value in the arguments array, and generally the nth ? placeholder gets
- replaced by the nth value in the arguments array.)?
- placeholders are done at the literal level, not as string
- concatenations, so this provides a way to dynamically insert
- parameters into a statement without risk of a SQL injection
- attack.? placeholder with the value of
+ the argument in the arguments array with the
+ same position. (So the first ? placeholder
+ gets bound to the first value in the arguments
+ array, and generally the nth ? placeholder gets bound to the nth value in the arguments
+ array.)? placeholders
+ is done at the literal level, not as string concatenations, so
+ this provides a way to dynamically insert parameters into a
+ statement without risk of a SQL injection attack.4.3 Asynchronous database API
interface Database {
- void transaction(in SQLTransactionCallback callback, optional in SQLTransactionErrorCallback errorCallback, optional in SQLVoidCallback successCallback);
- void readTransaction(in SQLTransactionCallback callback, optional in SQLTransactionErrorCallback errorCallback, optional in SQLVoidCallback successCallback);
+ void transaction(in SQLTransactionCallback callback, in optional SQLTransactionErrorCallback errorCallback, in optional SQLVoidCallback successCallback);
+ void readTransaction(in SQLTransactionCallback callback, in optional SQLTransactionErrorCallback errorCallback, in optional SQLVoidCallback successCallback);
readonly attribute DOMString version;
- void changeVersion(in DOMString oldVersion, in DOMString newVersion, in SQLTransactionCallback callback, in SQLTransactionErrorCallback errorCallback, in optional SQLVoidCallback successCallback);
+ void changeVersion(in DOMString oldVersion, in DOMString newVersion, in optional SQLTransactionCallback callback, in optional SQLTransactionErrorCallback errorCallback, in optional SQLVoidCallback successCallback);
};
[Callback=FunctionOnly, NoInterfaceObject]
@@ -645,14 +673,15 @@ interface changeVersion()
method.4.3.1 Executing SQL statements
transaction(),
+ 4.3.1 Executing SQL statements
transaction(),
readTransaction(),
and changeVersion()
methods invoke callbacks with SQLTransaction
objects.typedef sequence<any> ObjectArray;
interface SQLTransaction {
- void executeSql(in DOMString sqlStatement, optional in ObjectArray arguments, optional in SQLStatementCallback callback, optional in SQLStatementErrorCallback errorCallback);
+ void executeSql(in DOMString sqlStatement, in optional ObjectArray arguments, in optional SQLStatementCallback callback, in optional SQLStatementErrorCallback errorCallback);
};
[Callback=FunctionOnly, NoInterfaceObject]
@@ -715,19 +744,14 @@ interface changeVersion()
method.)
- SQLTransaction
- object as its only argument, and wait for that task to be
- run.SQLTransaction object as its only
+ argument, and wait for that task to be run.SQLTransaction
- object as its first argument and the new
- SQLResultSet object as its second argument, and wait
- for that task to be run.SQLTransaction object as its first argument and the
+ new SQLResultSet object as its second argument, and
+ wait for that task to be run.SQLTransaction object and a newly constructed
- SQLError object that represents the error that
- caused these substeps to be run as the two arguments,
+ SQLTransaction object and a newly
+ constructed SQLError object that represents the
+ error that caused these substeps to be run as the two arguments,
respectively, and wait for the task to be run.changeVersion()
method.)SQLError object
- that represents the last error to have occurred in this
- transaction. Rollback the transaction. Any still-pending statements
- in the transaction are discarded.SQLError object that represents the last error to have
+ occurred in this transaction. Rollback the transaction. Any
+ still-pending statements in the transaction are discarded.4.4 Synchronous database API
interface DatabaseSync {
+ 4.4 Synchronous database API
interface DatabaseSync {
void transaction(in SQLTransactionSyncCallback callback);
void readTransaction(in SQLTransactionSyncCallback callback);
readonly attribute DOMString version;
- void changeVersion(in DOMString oldVersion, in DOMString newVersion, in SQLTransactionSyncCallback callback);
+ void changeVersion(in DOMString oldVersion, in DOMString newVersion, in optional SQLTransactionSyncCallback callback);
};
[Callback=FunctionOnly, NoInterfaceObject]
@@ -866,14 +889,8 @@ interface Error code
2.)
- SQLException exception, and abort these steps.
- (Error code
- 0.)SQLTransactionSync object as stale.transaction(), readTransaction(),
and changeVersion()
- methods return SQLTransactionSync objects.// typedef sequence<any> ObjectArray;
+ methods invoke callbacks that are passed
+
SQLTransactionSync objects.// typedef sequence<any> ObjectArray;
interface SQLTransactionSync {
- SQLResultSet executeSql(in DOMString sqlStatement, optional in ObjectArray arguments);
+ SQLResultSet executeSql(in DOMString sqlStatement, in optional ObjectArray arguments);
};
SQLTransactionSync object is initially fresh, but it will be marked as stale
once it has been committed or rolled back.executeSql(sqlStatement, arguments) method is invoked, the user
agent must run the following algorithm:SQLTransactionSync object is stale, then throw an INVALID_STATE_ERR
@@ -970,14 +988,18 @@ interface S
zero (querying the database doesn't affect any rows).rows
attribute must return a SQLResultSetRowList
representing the rows returned, in the order returned by the
- database. If no rows were returned, then the object will be empty
- (its length will
- be zero).interface SQLResultSetRowList {
+ database. The same object must be returned each time. If no rows
+ were returned, then the object will be empty (its length will be
+ zero).interface SQLResultSetRowList {
readonly attribute unsigned long length;
getter any item(in unsigned long index);
-};SQLResultSetRowList objects lazily, or at least
- asynchronously, for better performance.SQLResultSetRowList objects have a length
+};SQLResultSetRowList objects when the object is
+ constructed (before the result set callback is invoked), rather than
+ on-demand, for better responsiveness. For the synchronous API, an
+ on-demand lazy evaluation implementation strategy is encouraged
+ instead, for better performance.SQLResultSetRowList objects have a length
attribute that must return the number of rows it represents (the
number of rows returned by the database). This is the length.length might be
expensive, and authors are thus encouraged to avoid using it (or
@@ -1007,10 +1029,10 @@ interface S
const unsigned short TIMEOUT_ERR = 7;
readonly attribute unsigned short code;
readonly attribute DOMString message;
-};code DOM
+};code IDL
attribute must return the most appropriate code from the table
below.message
- DOM attribute must return an error message describing the error
+ IDL attribute must return an error message describing the error
encountered. The message should be localized to the user's
language.SQLException exceptions:exception SQLException {
@@ -1025,8 +1047,8 @@ interface S
unsigned short code;
DOMString message;
};code
- DOM attribute must return the most appropriate code from the table
- below.message DOM
+ IDL attribute must return the most appropriate code from the table
+ below.message IDL
attribute must return an error message describing the error
encountered. The message should be localized to the user's
language.Constant
@@ -1085,7 +1107,9 @@ interface S
A lock for the transaction could not be obtained in a
reasonable time.
- 5 Web SQL
6 Disk space
5 Web SQL
6 Disk space
7 Privacy
7.1 User tracking
7.2 Cookie resurrection
7.3 Sensitivity of data
7.2 Sensitivity of data
8 Security
8.1 DNS spoofing attacks
8 Security
8.1 DNS spoofing attacks
8.5 SQL injection
? placeholder feature of the executeSql() method,
- and to never construct SQL statements on the fly.References
References