Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines two APIs for persistent data storage in Web clients: one for accessing key-value pair data and another for accessing structured data.
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 the W3C technical reports index at http://www.w3.org/TR/.
If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives) or whatwg@whatwg.org (subscribe, archives), or submit them using our public bug database. All feedback is welcome.
Implementors should be aware that this specification is not stable. Implementors who are not taking part in the discussions are likely to find the specification changing out from 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 specification is always available on the W3C CVS server. Change tracking for this document is available at the following location:
This specification is automatically generated from the corresponding section in the HTML5 specification's source document, as hosted in the WHATWG Subversion repository. Detailed change history for all of HTML5, including the parts that form this specification, can be found at the following locations:
The W3C Web Apps Working Group is the W3C working group responsible for this specification's progress along the W3C Recommendation track. This specification is the 23 April 2009 First Public Working 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 of the group; that page also includes instructions for disclosing a 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.
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
The only conformance class defined by this specification is user 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.
This specification relies on several other underlying specifications.
Many fundamental concepts from HTML5 are used by this specification. [HTML5]
The IDL blocks in this specification use the semantics of the WebIDL specification. [WebIDL]
The construction "a Foo object", where
Foo is actually an interface, is sometimes
used instead of the more accurate "an object implementing the
interface Foo".
The term DOM is used to refer to the API set made available to
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. [DOM3CORE]
A DOM 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 widely known. [ECMA262]
This section is non-normative.
This specification introduces two related mechanisms, similar to HTTP session cookies, for storing structured data on the client side. [RFC2109] [RFC2965]
The first is designed for scenarios where the user is carrying out a single transaction, but could be carrying out multiple transactions in different windows at the same time.
Cookies don't really handle this case well. For example, a user could be buying plane tickets in two different windows, using the same site. If the site used cookies to keep track of which ticket the user was buying, then as the user clicked from page to page in both windows, the ticket currently being purchased would "leak" from one window to the other, potentially causing the user to buy two tickets for the same flight without really noticing.
To address this, this specification introduces the sessionStorage DOM attribute.
Sites can add data to the session storage, and it will be accessible
to any page from the same site opened in that window.
For example, a page could have a checkbox that the user ticks to indicate that he wants insurance:
<label> <input type="checkbox" onchange="sessionStorage.insurance = checked"> I want insurance on this trip. </label>
A later page could then check, from script, whether the user had checked the checkbox or not:
if (sessionStorage.insurance) { ... }
If the user had multiple windows opened on the site, each one would have its own individual copy of the session storage object.
The second storage mechanism is designed for storage that spans multiple windows, and lasts beyond the current session. In particular, Web applications may wish to store megabytes of user data, such as entire user-authored documents or a user's mailbox, on the client side for performance reasons.
Again, cookies do not handle this case well, because they are transmitted with every request.
The localStorage DOM
attribute is used to access a page's local storage area.
The site at example.com can display a count of how many times the user has loaded its page by putting the following at the bottom of its page:
<p>
You have viewed this page
<span id="count">an untold number of</span>
time(s).
</p>
<script>
if (!localStorage.pageLoadCount)
localStorage.pageLoadCount = 0;
localStorage.pageLoadCount = parseInt(localStorage.pageLoadCount, 10) + 1;
document.getElementById('count').textContent = localStorage.pageLoadCount;
</script>
The use of parseInt() is needed when
dealing with numbers (integers in this case) because the storage
APIs are all string-based.
Each site has its own separate storage area.
Storage areas (both session storage and local storage) store strings. To store structured data in a storage area, you must first convert it to a string.
Storage interfaceinterface Storage {
readonly attribute unsigned long length;
[IndexGetter] DOMString key(in unsigned long index);
[NameGetter] DOMString getItem(in DOMString key);
[NameSetter] void setItem(in DOMString key, in DOMString data);
[NameDeleter] void removeItem(in DOMString key);
void clear();
};Each Storage object provides access to a list of
key/value pairs, which are sometimes called items. Keys and values
are strings. Any string (including the empty string) is a valid
key.
To store more structured data, authors may consider using the SQL interfaces instead.
Each Storage object is associated with a list of
key/value pairs when it is created, as defined in the sections on
the sessionStorage and localStorage attributes. Multiple
separate objects implementing the Storage interface can
all be associated with the same list of key/value pairs
simultaneously.
The object's indices of the supported indexed properties are the numbers in the range zero to one less than the number of key/value pairs currently present in the list associated with the object. If the list is empty, then there are no supported indexed properties.
The length
attribute must return the number of key/value pairs currently
present in the list associated with the object.
The key(n) method must return the name of the
nth key in the list. The order of keys is
user-agent defined, but must be consistent within an object between
changes to the number of keys. (Thus, adding or removing a key may change the
order of the keys, but merely changing the value of an existing key
must not.) If n is greater than or equal to the number of key/value pairs
in the object, then this method must raise an
INDEX_SIZE_ERR exception.
The names of the supported named properties on a
Storage object are the keys of each key/value pair
currently present in the list associated with the object.
The getItem(key) method must return the current
value associated with the given key. If the
given key does not exist in the list associated
with the object then this method must return null.
The setItem(key, value) method
must first check if a key/value pair with the given key already exists in the list associated with the
object.
If it does not, then a new key/value pair must be added to the list, with the given key and value.
If the given key does exist in the list, then it must have its value updated to the value given in the value argument.
If it couldn't set the new value, the method must raise an
QUOTA_EXCEEDED_ERR exception. (Setting could fail if,
e.g., the user has disabled storage for the domain, or if the quota
has been exceeded.)
The removeItem(key) method must cause the key/value
pair with the given key to be removed from the
list associated with the object, if it exists. If no item with that
key exists, the method must do nothing.
The setItem() and removeItem() methods must be
atomic with respect to failure. In the case of failure, the method
does nothing. That is, changes to the data storage area must either
be successful, or the data storage area must not be changed at
all.
The clear()
method must atomically cause the list associated with the object to
be emptied of all key/value pairs, if there are any. If there are
none, then the method must do nothing.
When the setItem(), removeItem(), and clear() methods are invoked, events
are fired on other HTMLDocument objects that can access
the newly stored or removed data, as defined in the sections on the
sessionStorage and localStorage attributes.
This specification does not require that the above methods wait until the data has been physically written to disk. Only consistency in what different scripts accessing the same underlying list of key/value pairs see is required.
sessionStorage attributeThe sessionStorage
attribute represents the set of storage areas specific to the
current top-level browsing context.
Each top-level browsing context has a unique set of session storage areas, one for each origin.
User agents should not expire data from a browsing context's session storage areas, but may do so when the user requests that such data be deleted, or when the UA detects that it has limited storage space, or for security reasons. User agents should always avoid deleting data while a script that could access that data is running. When a top-level browsing context is destroyed (and therefore permanently inaccessible to the user) the data stored in its session storage areas can be discarded with it, as the API described in this specification provides no way for that data to ever be subsequently retrieved.
The lifetime of a browsing context can be unrelated to the lifetime of the actual user agent process itself, as the user agent may support resuming sessions after a restart.
When a new HTMLDocument is created, the user agent
must check to see if the document's top-level browsing
context has allocated a session storage area for that
document's origin. If it has not, a new storage area
for that document's origin must be created.
The sessionStorage
attribute must return the Storage object associated
with that session storage area. Each Document object
must have a separate object for its Window's sessionStorage attribute.
When a new top-level browsing context is created by cloning an existing browsing context, the new browsing context must start with the same session storage areas as the original, but the two sets must from that point on be considered separate, not affecting each other in any way.
When a new top-level browsing context is created by
a script in an existing
browsing context, or by the user following a link in an
existing browsing context, or in some other way related to a
specific HTMLDocument, then the session storage area of
the origin of that HTMLDocument must be
copied into the new browsing context when it is created. From that
point on, however, the two session storage areas must be considered
separate, not affecting each other in any way.
When the setItem(), removeItem(), and clear() methods are called on a
Storage object x that is associated
with a session storage area, if the methods did something, then in
every HTMLDocument object whose Window
object's sessionStorage
attribute's Storage object is associated with the same
storage area, other than x, a storage event must be fired, as described below.
localStorage attributeThe localStorage
object provides a Storage object for an
origin.
User agents must have a set of local storage areas, one for each origin.
User agents should expire data from the local storage areas only for security reasons or when requested to do so by the user. User agents should always avoid deleting data while a script that could access that data is running. Data stored in local storage areas should be considered potentially user-critical. It is expected that Web applications will use the local storage areas for storing user-written documents.
When the localStorage
attribute is accessed, the user agent must check to see if it has
allocated a local storage area for the origin of the
Document of the Window object on which the
method was invoked. If it has not, a new storage area for that
origin must be created.
The user agent must then return the Storage object
associated with that origin's local storage area. Each
Document object must have a separate object for its
Window's localStorage attribute.
When the setItem(), removeItem(), and clear() methods are called on a
Storage object x that is associated
with a local storage area, if the methods did something, then in
every HTMLDocument object whose Window
object's localStorage
attribute's Storage object is associated with the same
storage area, other than x, a storage event must be fired, as described below.
Whenever the properties of a localStorage attribute's
Storage object are to be examined, returned, set, or
deleted, whether as part of a direct property access, when checking
for the presence of a property, during property enumeration, when
determining the number of properties present, or as part of the
execution of any of the methods or attributes defined on the
Storage interface. the user agent must first
obtain the storage mutex.
storage eventThe storage event
is fired when a storage area changes, as described in the previous
two sections (for session
storage, for local
storage).
When this happens, the user agent must dispatch an event with the
name storage, with no namespace, which does not bubble
but is cancelable, and which uses the StorageEvent
interface, at each Window object whose
Document object both has a Storage object
that is affected, and is fully active.
If the event is being fired due to an invocation of the
setItem() or removeItem() methods, the
event must have its key
attribute set to the name of the key in question, its oldValue attribute set to
the old value of the key in question, or null if the key is newly
added, and its newValue
attribute set to the new value of the key in question, or null if
the key was removed.
Otherwise, if the event is being fired due to an invocation of
the clear() method, the event
must have its key, oldValue, and newValue attributes set to
null.
In addition, the event must have its url attribute set to the address of the document
whose Storage object was affected; its source attribute set to the
that document's browsing context's
WindowProxy object, if the two documents are in the
same unit of related browsing contexts, or null
otherwise; and its storageArea attribute
set to the Storage object from the Window
object of the target Document that represents the same
kind of Storage area as was affected (i.e. session or
local).
interface StorageEvent : Event {
readonly attribute DOMString key;
readonly attribute DOMString oldValue;
readonly attribute DOMString newValue;
readonly attribute DOMString url;
readonly attribute WindowProxy source;
readonly attribute Storage storageArea;
void initStorageEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString keyArg, in DOMString oldValueArg, in DOMString newValueArg, in DOMString urlArg, in WindowProxy sourceArg, in Storage storageAreaArg);
void initStorageEventNS(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString keyArg, in DOMString oldValueArg, in DOMString newValueArg, in DOMString urlArg, in WindowProxy sourceArg, in Storage storageAreaArg);
};The initStorageEvent()
and initStorageEventNS()
methods must initialize the event in a manner analogous to the
similarly-named methods in the DOM3 Events interfaces. [DOM3EVENTS]
The key
attribute represents the key being changed.
The oldValue
attribute represents the old value of the key being changed.
The newValue
attribute represents the new value of the key being changed.
The url
attribute represents the address of the document whose key
changed.
The source attribute
represents the WindowProxy object of the browsing
context of the document whose key changed.
The storageArea
attribute represents the Storage object that was
affected.
Because of the use of the storage mutex, multiple browsing contexts will be able to access the local storage areas simultaneously in such a manner that scripts cannot detect any concurrent script execution.
Thus, the length
attribute of a Storage object, and the value of the
various properties of that object, cannot change while a script is
executing, other than in a way that is predictable by the script
itself.
This section is non-normative.
...
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 a domain 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.
The openDatabase() method on
the Window and WorkerUtils interfaces must
return a newly constructed Database object that
represents the database requested.
The openDatabaseSync()
method on the WorkerUtils interfaces must return a
newly constructed DatabaseSync object that represents
the database requested.
These methods take four arguments: a database name, a database version, a display name, and an estimated size, in bytes, of the data that will be stored in the database.
The database requested is the one with the given database name from the appropriate origin.
The openDatabase() method
on the Window object must use and create databases from
the origin of the active document of the
browsing context of the Window object on
which the method was invoked.
The openDatabase() and
openDatabaseSync()
methods on the WorkerUtils object must use and create
databases from the origin of the scripts in the
worker.
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.
If the database version provided is not the empty string, and the
database already exists but has a different version, or no version,
then the method must raise an INVALID_STATE_ERR
exception.
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.
Otherwise, if the database version provided is the empty string, or if the database doesn't yet exist, or if the database exists and the version requested is the same as the current version associated with the database, then the method must return an object representing the database that has the name that was given. If no such database exists, it must be created first.
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).
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.
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 used in place of SQL literals in the statement. [SQL]
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.
The result is the statement.
Implementation feedback is requested on what to do with arguments that are of types that are not supported by the underlying SQL backend. For example, SQLite doesn't support booleans, so what should the UA do if passed a boolean? The Gears team suggests failing, not silently converting types.
If the Database object that the
SQLTransaction or SQLTransactionSync
object was created from has an expected version
that is neither the empty string nor the actual version of the
database, then mark the statement as
bogus. (Error code
2.)
Otherwise, if the syntax of sqlStatement is
not valid (except for the use of ?
characters in the place of literals), or the statement uses
features that are not supported (e.g. due to security reasons), or
the number of items in the arguments array is
not equal to the number of ? placeholders in
the statement, or the statement cannot be parsed for some other
reason, then mark the statement as
bogus. (Error code
5.)
User agents must consider statements that use the BEGIN, COMMIT, and ROLLBACK SQL features as being unsupported (and thus
will mark them as bogus), so as to not let these statements
interfere with the explicit transactions managed by the database API
itself.
Otherwise, if the mode that was used to create the
SQLTransaction or SQLTransactionSync
object is read-only but the statement's main verb can modify the
database, mark the statement as bogus. (Error code 5.)
Only the statement's main verb (e.g. UPDATE, SELECT, DROP) is considered here. Thus, a statement like
"UPDATE test SET id=0 WHERE 0=1" would be
treated as potentially modifying the database for the purposes
of this step, even though it could never in fact have any
side-effects.
Return the statement.
The user agent must act as if the database was hosted in an otherwise completely empty environment with no resources. For 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.
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);
readonly attribute DOMString version;
void changeVersion(in DOMString oldVersion, in DOMString newVersion, in SQLTransactionCallback callback, in SQLTransactionErrorCallback errorCallback, in SQLVoidCallback successCallback);
};
[Callback=FunctionOnly, NoInterfaceObject]
interface SQLVoidCallback {
void handleEvent();
};
[Callback=FunctionOnly, NoInterfaceObject]
interface SQLTransactionCallback {
void handleEvent(in SQLTransaction transaction);
};
[Callback=FunctionOnly, NoInterfaceObject]
interface SQLTransactionErrorCallback {
void handleEvent(in SQLError error);
};The transaction()
and readTransaction()
methods takes one to three arguments. When called, these methods must
immediately return and then asynchronously run the transaction
steps with the transaction callback being the first
argument, the error callback being the second argument, if
any, the success callback being the third argument, if any,
and with no preflight operation or postflight
operation.
For the transaction() method, the
mode must be read/write. For the readTransaction()
method, the mode must be read-only.
On getting, the version attribute
must return the current version of the database (as opposed to the
expected
version of the Database object).
The changeVersion()
method allows scripts to atomically verify the version number and
change it at the same time as doing a schema update. When the method
is invoked, it must immediately return, and then asynchronously run
the transaction steps with the transaction
callback being the third argument, the error callback
being the fourth argument, the success callback being the
fifth argument, the preflight operation being the
following:
Check that the value of the first argument to the changeVersion() method
exactly matches the database's actual version. If it does not, then
the preflight operation fails.
...the postflight operation being the following:
changeVersion()
method.Database object's expected version to
the value of the second argument to the changeVersion()
method....and the mode being read/write.
The 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);
};
[Callback=FunctionOnly, NoInterfaceObject]
interface SQLStatementCallback {
void handleEvent(in SQLTransaction transaction, in SQLResultSet resultSet);
};
[Callback=FunctionOnly, NoInterfaceObject]
interface SQLStatementErrorCallback {
boolean handleEvent(in SQLTransaction transaction, in SQLError error);
};When the executeSql(sqlStatement, arguments, callback, errorCallback) method is invoked, the
user agent must run the following algorithm. (This algorithm is
relatively simple in that it doesn't actually execute any SQL
— the bulk of the work is actually done as part of the
transaction steps.)
If the method was not invoked during the execution of a
SQLTransactionCallback,
SQLStatementCallback, or
SQLStatementErrorCallback then raise an
INVALID_STATE_ERR exception. (Calls from inside a
SQLTransactionErrorCallback thus raise an
exception. The SQLTransactionErrorCallback handler is
only called once a transaction has failed, and no SQL statements
can be added to a failed transaction.)
Preprocess the SQL statement given as the first argument to the method (sqlStatement), using the second argument to the method as the arguments array, to obtain the statement.
If the second argument is omitted or null, then treat the arguments array as empty.
Queue up the statement in the transaction, along with the third argument (if any) as the statement's result set callback and the fourth argument (if any) as the error callback.
The transaction steps are as follows. These steps must be run asynchronously. These steps are invoked with a transaction callback, optionally an error callback, optionally a success callback, optionally a preflight operation, optionally a postflight operation, and with a mode that is either read/write or read-only.
Open a new SQL transaction to the database, and create a
SQLTransaction object that represents that
transaction. If the mode is read/write, the transaction must
have an exclusive write lock over the entire database. If the
mode is read-only, the transaction must have a shared read
lock over the entire database. The user agent should wait for an
appropriate lock to be available.
If an error occurred in the opening of the transaction (e.g. if the user agent failed to obtain an appropriate lock after an appropriate delay), jump to the last step.
If a preflight operation was defined for this
instance of the transaction steps, run that. If it fails, then jump
to the last step. (This is basically a hook for the changeVersion()
method.)
Queue a task to invoke the transaction
callback with the aforementioned SQLTransaction
object as its only argument, and wait for that task to be
run.
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 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, optionally a result set callback, and optionally an error callback.
If the statement is marked as bogus, jump to the "in case of error" steps below.
Execute the statement in the context of the transaction. [SQL]
If the statement failed, jump to the "in case of error" steps below.
Create a 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 SQLTransaction
object as its first argument and the new
SQLResultSet object as its second argument, and wait
for that task to be run.
If the callback was invoked and raised an exception, jump to the last step in the overall steps.
Move on to the next statement, if any, or onto the next overall step otherwise.
In case of error (or more specifically, if the above substeps say to jump to the "in case of error" steps), run the following substeps:
If the statement had an associated error callback, then
queue a task to invoke that error callback with the
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.
If the error callback returns false, then move on to the next statement, if any, or onto the next overall step otherwise.
Otherwise, the error callback did not return false, or there was no error callback. Jump to the last step in the overall steps.
If a postflight operation was defined for this
instance of the transaction steps, run that. If it fails, then jump
to the last step. (This is basically a hook for the
changeVersion()
method.)
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 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.
interface DatabaseSync {
SQLTransactionSync transaction();
SQLTransactionSync readTransaction();
readonly attribute DOMString version;
SQLTransactionSync changeVersion(in DOMString oldVersion, in DOMString newVersion);
};The transaction()
method must create a SQLTransactionSync
object for a read/write transaction, and return that
object.
The readTransaction()
method must create a SQLTransactionSync
object for a read/only transaction, and return that
object.
On getting, the version
attribute must return the current version of the database (as
opposed to the expected version of
the DatabaseSync object).
The changeVersion()
method allows scripts to atomically verify the version number and
change it at the same time as doing a schema update. When the method
is invoked, it must run the following steps:
Create a SQLTransactionSync object
for a read/write transaction. If this throws an exception, then
rethrow it and abort these steps.
Check that the value of the first argument to the changeVersion()
method exactly matches the database's actual version. If it does
not, then throw a SQLTransactionSync object and abort
these steps. (Error code
2.)
Return the SQLTransactionSync object.
When the SQLTransactionSync object's commit() method is
invoked, when the steps for that method invoke the postcommit
operation, the user agent must run the following steps:
changeVersion()
method.Database object's expected version to
the value of the second argument to the changeVersion()
method.When the user agent is to create a
SQLTransactionSync object for a transaction that
is either read/write or read-only, it must run the following
steps:
Open a new SQL transaction to the database, and create a
SQLTransactionSync object that represents that
transaction. If the mode is read/write, the transaction must
have an exclusive write lock over the entire database. If the
mode is read-only, the transaction must have a shared read
lock over the entire database. The user agent should wait for an
appropriate lock to be available.
If an error occurred in the opening of the transaction
(e.g. if the user agent failed to obtain an appropriate lock after
an appropriate delay), throw a SQLException exception
and abort these steps.
Return the newly created SQLTransactionSync
object.
The transaction(), readTransaction(),
and changeVersion()
methods return SQLTransactionSync objects.
// typedef sequence<any> ObjectArray;
interface SQLTransactionSync {
SQLResultSet executeSql(in DOMString sqlStatement, [Optional] in ObjectArray arguments);
void commit();
};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:
If the SQLTransactionSync object is stale, then throw an INVALID_STATE_ERR
exception.
Preprocess the SQL statement given as the first argument to the method (sqlStatement), using the second argument to the method as the arguments array, to obtain the statement.
If the second argument is omitted or null, then treat the arguments array as empty.
If the statement is marked as bogus, throw a
SQLException exception.
Execute the statement in the context of the transaction. [SQL]
If the statement failed, throw a SQLException
exception.
Create a SQLResultSet object that represents
the result of the statement.
Return the newly created SQLResultSet
object.
When the commit()
method is invoked, the user agent must run the following
algorithm:
Commit the transaction.
Mark the SQLTransactionSync object as stale.
If appropriate (i.e. if the changeVersion()
method created the SQLTransactionSync object), invoke
the postcommit operation.
If an error occurred in the committing of the transaction,
throw a SQLException exception.
The executeSql()
method invokes its callback with a SQLResultSet object
as an argument.
interface SQLResultSet {
readonly attribute long insertId;
readonly attribute long rowsAffected;
readonly attribute SQLResultSetRowList rows;
};The insertId
attribute must return the row ID of the row that the
SQLResultSet object's SQL statement inserted into the
database, if the statement inserted a row. If the statement inserted
multiple rows, the ID of the last row must be the one returned. If
the statement did not insert a row, then the attribute must instead
raise an INVALID_ACCESS_ERR exception.
The rowsAffected
attribute must return the number of rows that were affected by the
SQL statement. If the statement did not affected any rows, then the
attribute must return zero. For "SELECT" statements, this returns
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 {
readonly attribute unsigned long length;
[IndexGetter] any item(in unsigned long index);
};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.
The object's indices of the supported indexed properties are the numbers in the range zero to length-1, unless the length is zero, in which case there are no supported indexed properties.
The item(index) attribute must return the row
with the given index index. If there is no such
row, then the method must raise an INDEX_SIZE_ERR
exception.
Each row must be represented by a native ordered dictionary data
type. In the JavaScript binding, this must be Object.
Each row object must have one property (or dictionary entry) per
column, with those properties enumerating in the order that these
columns were returned by the database. Each property must have the
name of the column and the value of the cell, as they were returned
by the database.
Errors in the asynchronous database API are reported using
callbacks that have a SQLError object as one of their
arguments.
interface SQLError {
readonly attribute unsigned long code;
readonly attribute DOMString message;
};The code DOM
attribute must return the most appropriate code from the table
below.
The message
DOM attribute must return an error message describing the error
encountered. The message should be localized to the user's
language.
Errors in the synchronous database API are reported using
exceptions that implement the SQLException
interface:
exception SQLException {
readonly attribute unsigned long code;
readonly attribute DOMString message;
};The code
DOM attribute must return the most appropriate code from the table
below.
The message DOM
attribute must return an error message describing the error
encountered. The message should be localized to the user's
language.
The error codes are as follows:
| Code | Situation |
|---|---|
| 0 | The transaction failed for reasons unrelated to the database itself and not covered by any other error code. |
| 1 | The statement failed for database reasons not covered by any other error code. |
| 2 | The operation failed because the actual database version was
not what it should be. For example, a statement found that the
actual database version no longer matched the expected version
of the Database or DatabaseSync object,
or the Database.changeVersion()
or DatabaseSync.changeVersion()
methods were passed a version that doesn't match the actual
database version.
|
| 3 | The statement failed because the data returned from the database was too large. The SQL "LIMIT" modifier might be useful to reduce the size of the result set. |
| 4 | The statement failed because there was not enough remaining storage space, or the storage quota was reached and the user declined to give more space to the database. |
| 5 | The statement failed because of a syntax error, or the number
of arguments did not match the number of ?
placeholders in the statement, or the statement tried to use a
statement that is not allowed, such as BEGIN, COMMIT, or ROLLBACK, or the statement tried to use a verb
that could modify the database but the transaction was read-only.
|
| 6 | An INSERT, UPDATE, or REPLACE
statement failed due to a constraint failure. For example,
because a row was being inserted and the value given for the
primary key column duplicated the value of an existing row.
|
| 7 | A lock for the transaction could not be obtained in a reasonable time. |
User agents should limit the total amount of space allowed for storage areas and databases.
User agents should guard against sites storing data in the storage areas or databases of subdomains, e.g. storing up to the limit in a1.example.com, a2.example.com, a3.example.com, etc, circumventing the main example.com storage limit.
User agents may prompt the user when quotas are reached, allowing the user to grant a site more space. This enables sites to store many user-created documents on the user's computer, for instance.
User agents should allow users to see how much space each domain is using.
A mostly arbitrary limit of five megabytes per domain is recommended. Implementation feedback is welcome and will be used to update this suggestion in future.
A third-party advertiser (or any entity capable of getting content distributed to multiple sites) could use a unique identifier stored in its local storage area or in its client-side database to track a user across multiple sessions, building a profile of the user's interests to allow for highly targeted advertising. In conjunction with a site that is aware of the user's real identity (for example an e-commerce site that requires authenticated credentials), this could allow oppressive groups to target individuals with greater accuracy than in a world with purely anonymous Web usage.
There are a number of techniques that can be used to mitigate the risk of user tracking:
Blocking third-party storage: user agents may restrict access
to the localStorage and
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 iframes.
Expiring stored data: user agents may automatically delete stored data after a period of time.
For example, a user agent could treat third-party local storage areas as session-only storage, deleting the data once the user had closed all the browsing contexts that could access it.
This can restrict the ability of a site to track a user, as the site would then only be able to track the user across multiple 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.
Treating persistent storage as cookies: user agents should present the persistent storage and database features to the user in a way that does not distinguish them from HTTP session cookies. [RFC2109] [RFC2965]
This might encourage users to view persistent storage with healthy suspicion.
Site-specific white-listing of access to local storage areas and databases: user agents may allow sites to access session storage areas in an unrestricted manner, but require the user to authorize access to local storage areas and databases.
Origin-tracking of persistent storage data: user agents may record the origins of sites that contained content from third-party origins that caused data to be stored.
If this information is then used to present the view of data currently in persistent storage, it would allow the user to make informed decisions about which parts of the persistent storage to prune. Combined with a blacklist ("delete this data and prevent this domain from ever storing data again"), the user can restrict the use of persistent storage to sites that he trusts.
Shared blacklists: user agents may allow users to share their persistent storage domain blacklists.
This would allow communities to act together to protect their privacy.
While these suggestions prevent trivial use of these APIs for user tracking, they do not block it altogether. Within a single domain, a site can continue to track the user during a session, and can then pass all this information to the third party along with any identifying information (names, credit card numbers, addresses) obtained by the site. If a third party cooperates with multiple sites to obtain such information, a profile can still be created.
However, user tracking is to some extent possible even with no cooperation from the user agent whatsoever, for instance by using session identifiers in URLs, a technique already commonly used for innocuous purposes but easily repurposed for user tracking (even retroactively). This information can then be shared with other sites, using using visitors' IP addresses and other user-specific data (e.g. user-agent headers and configuration settings) to combine separate sessions into coherent user profiles.
If the user interface for persistent storage presents data in the persistent storage features 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.
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 identifying them as being from the same domain can access their local storage areas and databases.
Different authors sharing one host name, for example users
hosting content on geocities.com, all share one
persistent storage object and one set of databases. There is no
feature to restrict the access by pathname. Authors on shared hosts
are therefore recommended to avoid using the persistent storage
features, as it would be trivial for other authors to read from and
write to the same storage area or database.
Even if a path-restriction feature was made available, the usual DOM scripting security model would make it trivial to bypass this protection and access the data from any path.
The two primary risks when implementing these persistent storage features are letting hostile sites read information from other domains, and letting hostile sites write information that is then read from other domains.
Letting third-party sites read data that is not supposed to be read from their domain causes information leakage, For example, a user's shopping wishlist on one domain could be used by another domain for targeted advertising; or a user's work-in-progress confidential documents stored by a word-processing site could be examined by the site of a competing company.
Letting third-party sites write data to the storage areas of other domains can result in information spoofing, which is equally dangerous. For example, a hostile site could add items to a user's wishlist; or a hostile site could set a user's session identifier to a known ID that the hostile site can then use to track the user's actions on the victim site.
Thus, strictly following the origin model described in this specification is important for user security.
User agent implementors are strongly encouraged to audit all
their supported SQL statements for security implications. For
example, LOAD DATA INFILE is likely to pose
security risks and there is little reason to support it.
In general, it is recommended that user agents not support features that control how databases are stored on disk. For example, 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 ? placeholder feature of the executeSql() method,
and to never construct SQL statements on the fly.
This section will be written in a future draft.