On the HTML5 Indexed DB API - Part 1 of n

Over the years the web has increasingly transformed from being just a repository of content to a marketplace of full-fledged functional applications. The suite of technologies that are bandied about these days under the "HTML5" banner have as a fundamental goal, the enablement of the building of this new breed of software. In this post (and over the next post or two) we review a technology that solves an important piece of the application puzzle - that of managing storage and retrieval of user specific data on the client side, called "Indexed DB". For almost as long as the web has been around, there has been a need for web sites to track visitor specific information in one form or another. Using HTTP cookies has so far been pretty much the only standards based option available to web developers. While plug-in based alternatives in the form of Silverlight and Flash do exist, the typical challenges imposed on end users who either do not have the plug-in in question installed or are using the wrong version serves to complicate matters significantly. Let's first briefly review what the available alternatives are for a web developer seeking to solve the problem of managing client side storage today.

HTTP Cookies

HTTP cookies allow web applications to store small amounts of textual data on the client side using specially crafted HTTP headers. Access to this data is provided via the browser DOM. JavaScript code must be used to parse and make sense of the data. While this works, there are significant challenges in working with cookies:

  • Cookies are not allowed to be greater than 4 KB in size.
  • Cookies are transmitted with every request that the browser makes - even when it is requesting for things like images, script files or style sheets.
  • The programming model is not straightforward in that it is basically just text and you need to write code to parse and crack data stored in cookies.
  • Only textual data can be stored and retrieved.


Plug-ins have historically been the natural (if not the only) choice for web developers who have needs that are not catered to sufficiently by cookies. Technologies such as Silverlight, Flash and Google Gears come with their own brand of local storage options. While they are a better option as compared to cookies they do however present some unique challenges of their own:

  • As stated earlier, the primary issue is that user experience is less than stellar when you encounter cases where the user either does not have the plug-in in question installed or has the wrong version installed and must therefore upgrade. Often users are logged in to their computers with user accounts that do not have the required permission to install new software and hence are simply locked out of the web application or functionality completely.
  • Web developers must familiarize themselves with the specific tool stack associated with the plug-in.

DOM Storage

DOM storage is a part of the HTML5 suite of specifications and is meant to be a replacement for HTTP cookies. This is actually a viable client side storage option. The idea is to basically provide a key/value based storage API that allows web applications to store user specific data in a persistent manner. The API is simple to use and it just works! However, there are some limitations to how it can be put to use which are to a large extent deliberate and by design:

  • You can only store strings in DOM storage, i.e., both key and value must be JavaScript strings. You can however use JSON serialization to manage the storage and retrieval of objects.
  • Data stored in DOM storage is scoped by the domain, i.e., it will not be possible for code running in one domain to access DOM storage data stored under the context of a different domain. While this is a good thing, the limitation however is that it is not possible to scope this with a greater level of granularity - say by specific URLs within a domain.
  • There is no mechanism to iterate through all the data stored in DOM storage. You can only request the value for a specific key that you already know.

With that brief overview of the alternatives let us move on to the topic of this post - the Indexed Database API.

What is Indexed DB?

An Indexed DB is basically a persistent data store in the browser - a database on the client side. It defines an API that allows the storage and retrieval of key/value data. Like regular relational databases, it maintains indexes over the records it stores and developers use the Indexed DB JavaScript API to locate records by key or by looking up an index. Each database is scoped by "origin", i.e. the domain of the site that creates the database. The database is transactional and provides a means for traversing the data in a deterministic order.

The Indexed DB API includes a synchronous and an asynchronous version of pretty much all the interfaces. The asynchronous API is meant to be used from web apps when you are interacting with the database directly from the UI thread where having an API call block on an I/O operation is not acceptable. All blocking calls work asynchronously and results are reported via callbacks. The synchronous API counterparts are identical to the asynchronous versions except for the fact that there are no callbacks and results are returned directly.

A word on the status of the spec

The Indexed DB specification is currently (i.e., when this post was written) in draft status and should not be considered as being production ready. The specification itself is under active development and developers are encouraged to review it only with the objective of familiarizing themselves with an up and coming standard. Do not use it in production sites yet!

Setting your development environment up

Before we proceed with the API itself, you might want to spend some time setting up your development environment up. For Internet Explorer (IE), an experimental implementation of the specification is available for download from Microsoft's HTML5 Labs site. "HTML5 Labs" is an initiative from Microsoft for publishing prototype implementations of various key HTML5 specifications so that developers are able to experiment with them and provide feedback. The prototype implementation for Indexed DB works on Internet Explorer versions 8 and up and installing it is fairly straightforward.

  1. Download the prototype by clicking on the link "Download the Protoype now!" from here.

  2. Unzip the downloaded file.

  3. If you are running a 32-bit version of Windows then run vcredist_x86.exe.

  4. Register "sqlcejse40.dll" by running the following command from an elevated command prompt:

    regsvr32 sqlcejse40.dll

    If everything goes well, then you should see a screen such as the following:


Alternatively, get a recent version of Google Chrome or Firefox and you should be all set.

Coming up.

Now that we have the fundamentals covered, we'll go ahead and get started with the API itself from the next post. Stay tuned!

comments powered by Disqus