<html><title>IndexedDB Tutorial</title>
<script>
// This is a tutorial that highlights many of the features of IndexedDB along witha number of
// caveats that currently exist in Chromium/WebKit but which will hopefully be improved upon
// over time.
//
// The latest version of the spec can be found here:
// http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html but note that there are quite a
// few bugs currently opened against it and some major unresolved issues (like whether dynamic
// transactions should be in for v1). Many of the bugs are filed here:
// http://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&component=Indexed+Database+API&longdesc_type=allwordssubstr&longdesc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=substring&email2=&bug_id_type=anyexact&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&known_name=IndexedDB&query_based_on=IndexedDB&field0-0-0=noop&type0-0-0=noop&value0-0-0=
// Discussion happens on public-webapps@w3.org
//
// Although not user friendly, additional capabilities and example code can be found in the
// tests for IndexedDB which are here:
// http://trac.webkit.org/browser/trunk/LayoutTests/storage/indexeddb
//
// This document is currently maintained by Jeremy Orlow <jorlow@chromium.org>
// This is not an ideal layout test since it doesn't verify things as thoroughly as it could,
// but adding such content would make it much more cluttered and thus wouldn't serve its primary
// goal of teaching people IndexedDB. That said, it does have a good amount of coverage and
// serves as a living document describing what's expected to work and how within WebKit so it
// seems well worth having checked in.
if (window.layoutTestController) {
layoutTestController.dumpAsText();
layoutTestController.waitUntilDone();
}
function setup()
{
// As this API is still experimental, it's being shipped behind vendor specific prefixes.
if ('webkitIndexedDB' in window) {
indexedDB = webkitIndexedDB;
IDBCursor = webkitIDBCursor;
IDBKeyRange = webkitIDBKeyRange;
IDBTransaction = webkitIDBTransaction;
}
// This tutorial assumes that Mozilla and WebKit match each other which isn't true at the
// moment, but we can hope it'll become true over time.
if ('moz_indexedDB' in window) {
indexedDB = moz_indexedDB;
// Not implemented by them yet. I'm just guessing what they'll be.
IDBCursor = moz_IDBCursor;
IDBKeyRange = moz_IDBKeyRange;
IDBTransaction = moz_IDBTransaction;
}
}
function log(txt)
{
document.getElementById("logger").innerHTML += txt + "<br>";
}
function logError(txt)
{
log("<font color=red>" + txt + "</font>");
}
function start()
{
setup();
// This is an example of one of the many asynchronous commands in IndexedDB's async interface.
// Each returns an IDBRequest object which has "success" and "error" event handlers. You can use
// "addEventListener" if you'd like, but I'm using the simpler = syntax. Only one or the other
// will fire. You're guaranteed that they won't fire until control is returned from JavaScript
// execution.
var request = indexedDB.open("tutorialDB");
request.onsuccess = onOpen;
request.onerror = unexpectedError;
}
function unexpectedError()
{
// If an asynchronous call results in an error, an "error" event will fire on the IDBRequest
// object that was returned and the event's code and message attributes will be populated with
// the correct values.
logError("Error " + event.code + ": " + event.message);
// Unfortunately, Chromium/WebKit do not implicitly abort a transaction when an error occurs
// within one of its async operations. In the future, when an error occurs and the event is
// not canceled, the transaction will be aborted.
if (currentTransaction)
currentTransaction.abort();
}
function onOpen()
{
// If an asynchronous call results in success, a "success" event will fire on the IDBRequest
// object that was returned (i.e. it'll be the event target), which means that you can simply
// look at event.target.result to get the result of the call. In some cases, the expected
// result will be null.
window.db = event.target.result;
// The IDBDatabase object has a "version" attribute. This can only be set by calling
// "setVersion" on the database and supplying a new version. This also starts a new
// transaction which is very special. There are many details and gotchas surrounding
// setVersion which we'll get into later.
if (db.version == "1.0") {
// We could skip setting up the object stores and indexes if this were a real application
// that wasn't going to change things without changing the version number. But since this
// is both a tutorial and a living document, we'll go on and set things up every time we run.
}
var request = db.setVersion("1.0");
request.onsuccess = onSetVersion;
request.onerror = unexpectedError;
}
function onSetVersion()
{
// We are now in a setVersion transaction. Such a transaction is the only place where one
// can add or delete indexes and objectStores. The result (property of the request) is an
// IDBTransaction object that has "complete" and "abort" event handlers which tell
// us when the transaction has committed, aborted, or timed out.
window.currentTransaction = event.target.result;
currentTransaction.oncomplete = onSetVersionComplete;
currentTransaction.onabort = unexpectedAbort;
// Delete existing object stores.
while (db.objectStoreNames.length)
db.deleteObjectStore(db.objectStoreNames[0]);
// Now that we have a blank slate, let's create an objectStore. An objectStore is simply an
// ordered mapping of keys to values. We can iterate through ranges of keys or do individual
// lookups. ObjectStores don't have any schema.
//
// Keys can be integers, strings, or null. (The spec also defines dates and there's talk of
// handling arrays, but these are not implemented yet in Chromium/WebKit.) Values can be
// anything supported by the structured clone algorithm
// (http://dev.w3.org/html5/spec/Overview.html#internal-structured-cloning-algorithm) which
// is a superset of what can be expressed in JSON. (Note that Chromium/WebKit does not fully
// implement the structured clone algorithm yet, but it definitely handles anything JSON
// serializable.)
//
// There are two types of objectStores: ones where the path is supplied manually every time a
// value is inserted and those with a "key path". A keyPath is essentially a JavaScript
// expression that is evaluated on every value to extract a key. For example, if you pass in
// the value of "{fname: 'john', lname: 'doe', address: {street: 'Buckingham Palace", number:
// 76}, siblings: ["Nancy", "Marcus"], id: 22}" and an objectStore has a keyPath of "id" then
// 22 will be the key for this value. In objectStores, each key must be unique.
//
// Note that the exact syntax allowed for keyPaths is not yet well specified, but
// Chromium/WebKit currently allows paths that are multiple levels deep within an object and
// allows that to be intermixed with array dereferences. So, for example, a key path of
// "address.number" or "siblings[0]" would be legal (provided every entry had an address with
// a number attribute and at least one sibling). You can even go wild and say
// "foo[0][2].bar[0].baz.test[1][2][3]". It's possible this will change in the future though.
//
// If you set autoIncrement (another optional parameter), IndexedDB will generate a key
// for your entry automatically. And if you have a keyPath set, it'll set the value at
// the location of the keyPath _in the database_ (i.e. it will not modify the value you pass
// in to put/add). Unfortunately autoIncrement is not yet implemented in Chromium/WebKit.
//
// Another optional parameter, "evictable" is not yet implemented. When it is, it'll hint
// which data should be deleted first if the browser decides this origin is using too much
// storage. (The alternative is that it'll suggest the user delete everything from the
// origin, so it's in your favor to set it approperately!) This is great for when you have
// some absolutely critical data (like unset emails) and a bunch of less critical, (but
// maybe still important!) data.
//
// All of these options can be passed into createObjectStore via its (optional) second
// parameter. So, if you wanted to define all, You'd do {keyPath: "something",
// evictable: true, autoIncrement: true}. You can also pass in subsets of all three or
// omit the object (since it's optional).
//
// Let's now create an objectStore for people. We'll supply a key path in this case.
var objectStore = db.createObjectStore("people", {keyPath: "id"});
// Notice that it returned synchronously. The rule of thumb is that any call that touches (in
// any way) keys or values is asynchronous and any other call (besides setVersion and open) are
// asynchronous.
//
// Now let's create some indexes. Indexes allow you to create other keys via key paths which
// will also point to a particular value in an objectStore. In this example, we'll create
// indexes for a persons first and last name. Indexes can optionally be specified to not be
// unique, which is good in the case of names. The first parameter is the name of the index.
// Second is the key path. The third specifies uniqueness.
var fname = objectStore.createIndex("fname", "fname", false);
var lname = objectStore.createIndex("lname", "lname", false);
// Note that if you wanted to delete these indexes, you can either call objectStore.deleteIndex
// or simply delete the objectStores that own the indexes.
//
// If we wanted to, we could populate the objectStore with some data here or do anything else
// allowed in a normal (i.e. non-setVersion) transaction. This is useful so that data migrations
// can be atomic with changes to the objectStores/indexes.
//
// Because we haven't actually made any new asynchronous requests, this transaction will
// start committing as soon as we leave this function. This will cause oncomplete event handler
// for the transaction will fire shortly after. IndexedDB transactions commit whenever control is
// returned from JavaScript with no further work being queued up against the transaction. This
// means one cannot call setTimeout, do an XHR, or anything like that and expect my transaction
// to still be around when that completes.
}
function unexpectedAbort()
{
logError("A transaction aborted unexpectedly!");
}
function onSetVersionComplete()
{
// Lets create a new transaction and then not schedule any work on it to watch it abort itself.
// Transactions (besides those created with setVersion) are created synchronously. Like
// createObjectStore, transaction optionally takes in various optional parameters.
//
// First of all is the parameter "objectStoreNames". If you pass in a string, we lock just that
// objectStore. If you pass in an array, we lock those. Otherwise (for example, if you omit it
// or pass in null/undefined) we lock the whole database. By specifying locks over fewer
// objectStores you make it possible for browsers to run transactions concurrently. That said,
// Chromium/WebKit does not support this yet.
//
// Next is "mode" which specifies the locking mode. The default is READ_ONLY (i.e. a shared lock).
// That's fine for this case, but later we'll ask for IDBTransaction.READ_WRITE. At the moment,
// Chromium/WebKit pretends every transaction is READ_WRITE, which is kind of bad.
window.currentTransaction = db.transaction([], IDBTransaction.READ_WRITE);
currentTransaction.oncomplete = unexpectedComplete;
currentTransaction.onabort = onTransactionAborted;
// Verify that "people" is the only object store in existance. The objectStoreNames attribute is
// a DOMStringList which is somewhat like an array.
var objectStoreList = db.objectStoreNames;
if (objectStoreList.length != 1
|| !objectStoreList.contains("people")
|| objectStoreList.item(0) != "people"
|| objectStoreList[0] != "people") {
logError("Something went wrong.");
}
// Let's grab a handle to the objectStore. This handle is tied to the transaction that creates
// it and thus becomes invalid once this transaction completes.
var objectStore = currentTransaction.objectStore("people");
if (!objectStore)
logError("Something went wrong.");
// If we try to grab an objectStore that doesn't exist, IndexedDB throws an exception.
try {
currentTransaction.objectStore("x");
logError("Something went wrong.");
} catch (e) {
// Note that the error messages in exceptions are mostly lies at the moment. The reason is
// that the spec re-uses exception codes for existing exceptions and there's no way we can
// disambiguate between the two. The best work-around at the moment is to look at
// http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html#the-idbdatabaseexception-interface
// to figure out what the number corresponds to. We will try to resolve this soon in spec-land.
}
// Verify that fname and lname are the only indexes in existance.
if (objectStore.indexNames.length != 2)
logError("Something went wrong.");
// Note that no async actions were ever queued up agianst our transaction, so it'll abort once
// we leave this context.
}
function unexpectedComplete()
{
logError("A transaction committed unexpectedly!");
}
function onTransactionAborted()
{
// Now let's make a real transaction and a person to our objectStore. Just to show it's possible,
// we'll omit the objectStoreNames parameter which means we'll lock everything even though we only
// ever access "people".
window.currentTransaction = db.transaction([], IDBTransaction.READ_WRITE);
currentTransaction.onabort = unexpectedAbort;
var people = currentTransaction.objectStore("people");
var request = people.put({fname: 'John', lname: 'Doe', id: 1}); // If our objectStore didn't have a key path, the second parameter would have been the key.
request.onsuccess = onPutSuccess;
request.onerror = unexpectedError;
// While we're at it, why not add a few more? Multiple queued up async commands will be executed
// sequentially (though there is talk of prioritizing cursor.continue--see discussion below). Since
// we don't care about the individual commands' successes, we'll only bother with on error handlers.
//
// Remember that our implementation of unexpectedError should abort the "currentTransaction" in the
// case of an error. (Though no error should occur in this case.)
people.put({fname: 'Jane', lname: 'Doe', id: 2}).onerror = unexpectedError;
people.put({fname: 'Philip', lname: 'Fry', id: 3}).onerror = unexpectedError;
// Not shown here are the .delete method and .add (which is
// like .put except that it fires an onerror if the element already exists).
}
function onPutSuccess()
{
// Result is the key used for the put.
if (event.target.result !== 1)
logError("Something went wrong.");
// We should be able to request the transaction via event.transaction from within any event handler
// (like this one) but this is not yet implemented in Chromium/WebKit. As a work-around, we use the
// global "currentTransaction" variable we set above.
currentTransaction.oncomplete = onPutTransactionComplete;
}
function onPutTransactionComplete()
{
// OK, now let's query the people objectStore in a couple different ways. First up, let's try get.
// It simply takes in a key and returns a request whose result will be the value. Note that here
// we're passing in an array for objectStoreNames rather than a simple string.
window.currentTransaction = db.transaction(["people"], IDBTransaction.READ_WRITE, 0);
currentTransaction.onabort = unexpectedAbort;
var people = currentTransaction.objectStore("people");
var request = people.get(1);
request.onsuccess = onGetSuccess;
request.onerror = unexpectedError;
// Note that multiple objectStore (or index) method calls will return different objects (that still
// refer to the same objectStore/index on disk).
people.someProperty = true;
if (currentTransaction.objectStore("people").someProperty)
logError("Something went wrong.");
}
function onGetSuccess()
{
if (event.target.result.fname !== "John")
logError("Something went wrong.");
// Requests (which are our event target) also have a source attribute that's the object that
// returned the request. In this case, it's our "people" objectStore object.
var people = event.target.source;
// Now let's try opening a cursor from id 1 (exclusive/open) to id 3 (inclusive/closed). This means
// we'll get the objects for ids 2 and 3. You can also create cursors that are only right or only
// left bounded or ommit the bound in order to grab all objects. You can also specify a direction
// which can be IDBCursor.NEXT (default) for the cursor to move forward, NEXT_NO_DUPLICATE to only
// return unique entires (only applies to indexes with unique set to false), PREV to move backwards,
// and PREV_NO_DUPLICATE.
var keyRange = IDBKeyRange.bound(1, 3, true, false);
var request = people.openCursor(keyRange, IDBCursor.NEXT);
request.onsuccess = onObjectStoreCursor;
request.onerror = unexpectedError;
}
function onObjectStoreCursor()
{
// The result of openCursor is an IDBCursor object or null if there are no (more--see below)
// records left.
var cursor = event.target.result;
if (cursor === null) {
cursorComplete(event.target.source); // The soruce is still an objectStore.
return;
}
// We could use these values if we wanted to.
var key = cursor.key;
var value = cursor.value;
// cursor.count is probably going to be removed.
// cursor.update and .remove are not yet implemented in Chromium/WebKit.
// cursor.continue will reuse the same request object as what openCursor returned. In the future,
// we MAY prioritize .continue() calls ahead of all other async operations queued up. This will
// introduce a level of non-determinism but should speed things up. Mozilla has already implemented
// this non-standard behavior, from what I've head.
event.target.result.continue();
}
function cursorComplete(objectStore)
{
// While still in the same transaction, let's now do a lookup on the lname index.
var lname = objectStore.index("lname");
// Note that the spec has not been updated yet, but instead of get and getObject, we now
// have getKey and get. The former returns the objectStore's key that corresponds to the key
// in the index. get returns the objectStore's value that corresponds to the key in the
// index.
var request = lname.getKey("Doe");
request.onsuccess = onIndexGetSuccess;
request.onerror = unexpectedError;
}
function onIndexGetSuccess()
{
// Because we did "getKey" the result is the objectStore's key.
if (event.target.result !== 1)
logError("Something went wrong.");
// Similarly, indexes have openCursor and openKeyCursor. We'll try a few of them with various
// different IDBKeyRanges just to demonstrate how to use them, but we won't bother to handle
// the onsuccess conditions.
var lname = event.target.source;
lname.openCursor(IDBKeyRange.lowerBound("Doe", false), IDBCursor.NEXT_NO_DUPLICATE);
lname.openCursor(null, IDBCursor.PREV_NO_DUPLICATE);
lname.openCursor(IDBKeyRange.upperBound("ZZZZ"));
lname.openCursor(IDBKeyRange.only("Doe"), IDBCursor.PREV);
lname.openCursor();
lname.openKeyCursor();
// We should be able to request the transaction via event.transaction from within any event handler
// (like this one) but this is not yet implemented in Chromium/WebKit. As a work-around, we use the
// global "currentTransaction" variable we set above.
currentTransaction.oncomplete = onAllDone;
}
function onAllDone()
{
log("Everything worked!");
if (window.layoutTestController)
layoutTestController.notifyDone();
}
// The way setVersion is supposed to work:
// To keep things simple to begin with, objectStores and indexes can only be created in a setVersion
// transaction and one can only run if no other connections are open to the database. This is designed
// to save app developers from having an older verison of a web page that expects a certain set of
// objectStores and indexes from breaking in odd ways when things get changed out from underneith it.
// In the future, we'll probably add a more advanced mechanism, but this is it for now.
// Because a setVersion transaction could stall out nearly forever until the user closes windows,
// we've added a "blocked" event to the request object returned by setVersion. This will fire if the
// setVersion transaction can't begin because other windows have an open connection. The app can then
// either pop something up telling the user to close windows or it can tell the other windows to call
// .close() on their database handle. .close() halts any new transactions from starting and waits for
// the existing ones to finish. It then closes the connection and any indexedDB calls afterwards are
// invalid (they'll probably throw, but this isn't specified yet). We may specify .close() to return
// an IDBRequest object so that we can fire the onsuccess when the close completes.
// Once inside a setVersion transaction, you can do anything you'd like. The one connection which
// was allowed to stay open to complete the setVersion transaction will stay alive. Multiple
// setVersion transactions can be queued up at once and will fire in the order queued (though
// this obviously only works if they're queued in the same page).
//
// The current status of setVersion in Chromium/WebKit:
// In Chromium/WebKit we currently don't enforce the "all connections must be closed before a
// setVersion transaction starts" rule. We also don't implement database.close() or have a blocked
// event on the request .setVersion() returns.
//
// The current status of workers:
// Chromium/WebKit do not yet support workers using IndexedDB. Support for the async interface
// will likely come before the sync interface. For now, a work-around is using postMessage to tell
// the page what to do on the worker's behalf in an ad-hoc manner. Anything that can be serialized
// to disk can be serialized for postMessage.
</script>
<body onload="start()">
Please view source for more information on what this is doing and why...<br><br>
<div id="logger"></div>
</body>
</html>