storage/indexeddb/tutorial.html

<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>