--- html5/webdatabase/Overview.html 2009/09/14 07:38:33 1.31 +++ html5/webdatabase/Overview.html 2010/08/09 23:13:10 1.91 @@ -1,4 +1,4 @@ -Web Database
-

W3C

-

Web Database

-

W3C Working Draft 10 September 2009

+ body.dfnEnabled dfn { cursor: pointer; } + .dfnPanel { + display: inline; + position: absolute; + z-index: 10; + height: auto; + width: auto; + padding: 0.5em 0.75em; + font: small sans-serif, Droid Sans Fallback; + background: #DDDDDD; + color: black; + border: outset 0.2em; + } + .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; } + .dfnPanel :link, .dfnPanel :visited { color: black; } + .dfnPanel p { font-weight: bolder; } + .dfnPanel * + p { margin-top: 0.25em; } + .dfnPanel li { list-style-position: inside; } + + #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; } + #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; } + #configUI p label { display: block; } + #configUI #updateUI, #configUI .loginUI { text-align: center; } + #configUI input[type=button] { display: block; margin: auto; } -
This Version:
-
http://www.w3.org/TR/2009/WD-webdatabase-20090910/
-
Latest Published Version:
+
+

W3C

+

Web SQL Database

+

Editor's Draft 9 August 2010

+
Latest Published Version:
http://www.w3.org/TR/webdatabase/
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/
+
Editors:
Ian Hickson, Google, Inc.

Copyright - © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C @@ -194,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.

Status of This document

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 @@ -210,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 @@ -219,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 10 September 2009 First Public Working 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 @@ -244,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.

Table of contents

+ 6 of the W3C Patent Policy.

Table of Contents

  1. 1 Introduction
    2. @@ -271,7 +291,7 @@
    1. 7.1 User tracking
    2. 7.2 Sensitivity of data
    -
  2. 8 Security +
  3. 8 Security
    1. 8.1 DNS spoofing attacks
    2. 8.2 Cross-directory attacks
      3. @@ -356,13 +376,21 @@ prepareDatabase(function(db) { agents.

      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.

      2.1 Dependencies

      This specification relies on several other underlying - specifications.

      HTML5
      + platform-specific limitations.

      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.

      2.1 Dependencies

      This specification relies on several other underlying + specifications.

      HTML
      -

      Many fundamental concepts from HTML5 are used by this - specification. [HTML5]

      +

      Many fundamental concepts from HTML are used by this + specification. [HTML]

      @@ -382,7 +410,7 @@ prepareDatabase(function(db) { scripts in Web applications, and does not necessarily imply the existence of an actual Document object or of any other Node objects as defined in the DOM Core - specifications. [DOMCORE]

      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 @@ -445,6 +473,10 @@ interface Dat +

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

      4. +

    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 @@ -517,22 +549,22 @@ interface Dat instead of the user agent prompting the user for permission to increase the quota every five megabytes.

      4.2 Parsing and processing SQL statements

      When the user agent is to preprocess a SQL statement sqlStatement with an array of arguments arguments, it must run the following steps:

      1. 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]

      2. -

        Replace each ? 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.)

        - -

        Substitutions for ? - 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.

        +

        Bind each ? 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.)

        + +

        Binding the ? 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.

        The result is the statement.

        @@ -588,8 +620,8 @@ interface Dat example, attempts to read from or write to the file system will fail.

        A future version of this specification will probably define the exact SQL subset required in more detail.

        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 optional SQLTransactionCallback callback, in optional SQLTransactionErrorCallback errorCallback, in optional SQLVoidCallback successCallback);
@@ -649,7 +681,7 @@ interface 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]
@@ -775,14 +807,13 @@ 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 changeVersion()
     method.)
        
 
-    
        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.
        3. @@ -792,19 +823,19 @@ interface 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. -

      The task source for these tasks is the database access task +

    The task source for these tasks is the database access task source.

    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, optional in SQLTransactionSyncCallback callback);
+  void changeVersion(in DOMString oldVersion, in DOMString newVersion, in optional SQLTransactionSyncCallback callback);
 };
 
 [Callback=FunctionOnly, NoInterfaceObject]
@@ -906,7 +937,7 @@ interface 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);
 };
    A SQLTransactionSync object is initially fresh, but it will be marked as stale
   once it has been committed or rolled back.
    When the executeSql(sqlStatement, arguments) method is invoked, the user
   agent must run the following algorithm:
    1. If the SQLTransactionSync object is stale, then throw an INVALID_STATE_ERR
@@ -957,14 +988,18 @@ interface S
   zero (querying the database doesn't affect any rows).
      The 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);
-};
      Implementors are encouraged to implement
-  SQLResultSetRowList objects lazily, or at least
-  asynchronously, for better performance.
      SQLResultSetRowList objects have a length
+};
      For the asynchronous API, implementors are
+  encouraged to prefetch all the data for
+  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.
      Fetching the length might be
   expensive, and authors are thus encouraged to avoid using it (or
@@ -1072,7 +1107,9 @@ interface S
      A lock for the transaction could not be obtained in a
      reasonable time.
 
-  
      5 Web SQL
      Need to define the SQL dialect.
      6 Disk space
      User agents should limit the total amount of space allowed for
+  
      5 Web SQL
      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].
      6 Disk space
      User agents should limit the total amount of space allowed for
   databases.
   
   
      User agents should guard against sites storing data under the
@@ -1088,7 +1125,8 @@ interface S
   future.
      7 Privacy
      7.1 User tracking
      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
@@ -1103,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
@@ -1113,8 +1152,8 @@ interface S
    
      Expiring stored data
      
    
      
 
-    
      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
@@ -1122,10 +1161,11 @@ 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.
      
 
-    
 
    
      
 
@@ -1134,12 +1174,10 @@ interface S
 
     
      If users attempt to protect their privacy by clearing cookies
     without also clearing data stored in the
-
-    database
+    relevant databases,
     
-
-    feature, sites can defeat those attempts by using the two features
-    as redundant backup for each other. User agents should present the
+    sites can defeat those attempts by using the two features as
+    redundant backup for each other. User agents should present the
     interfaces for clearing these in a way that helps users to
     understand this possibility and enables them to delete data in all
     persistent storage features simultaneously. [COOKIES]
      
@@ -1149,12 +1187,14 @@ interface S
    
      Site-specific white-listing of access to
    databases
    
+   
    
      
    
      
 
     
      User agents may require the user to authorize access to
     databases before a site can use the feature.
      
     
+    
 
    
      
 
@@ -1203,10 +1243,10 @@ interface S
   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.
      8 Security
      8.1 DNS spoofing attacks
      Because of the potential for DNS spoofing attacks, one cannot
+  it is promptly deleted from the underlying storage.
      8 Security
      8.1 DNS spoofing attacks
      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.
   
@@ -1242,43 +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.
      8.5 SQL injection
      Authors are strongly recommended to make use of the ? placeholder feature of the executeSql() method,
-  and to never construct SQL statements on the fly.
      References
      All references are normative unless marked "Non-normative".
      [COOKIES]
      
+  and to never construct SQL statements on the fly.
      References
      All references are normative unless marked "Non-normative".
      [COOKIES]
      
    
-   
      HTTP State
-   Management Mechanism, A. Barth. IETF, August 2009.
      
+   
      HTTP State
+   Management Mechanism, A. Barth. IETF.
      
 
    
      [DOMCORE]
      
    
      Document
    Object Model (DOM) Level 3 Core Specification, A. Le
    Hors, P. Le Hegaret, L. Wood, G. Nicol, J. Robie, M. Champion,
-   S. Byrnes. W3C, April 2004.
      
+   S. Byrnes. W3C.
    
 
    
      [ECMA262]
      
    
      ECMAScript
-   Language Specification. ECMA, December 1999.
      
+   Language Specification. ECMA.
 
-   
      [HTML5]
      
-   
-   
      HTML5,
-   I. Hickson. WHATWG, August 2009.
      
+   
      [HTML]
      
+   
      HTML,
+   I. Hickson. WHATWG.
      
 
    
      [RFC2119]
      
    
      Key words for use in
-   RFCs to Indicate Requirement Levels, S. Bradner. IETF, March
-   1997.
      
+   RFCs to Indicate Requirement Levels, S. Bradner. IETF.
 
    
      [SQL]
      
    
      The precise dialect has not yet been specified.
      
@@ -1286,9 +1320,9 @@ interface S
    
      [WEBIDL]
      
    
    
      Web
-   IDL, C. McCormack. W3C, July 2009.
      
+   IDL, C. McCormack. W3C.