Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A polyfill for IndexedDB using WebSql
JavaScript HTML Other
branch: master

IndexedDB Polyfill

Use a single offline storage API across all desktop and mobile browsers

Build Status Dependencies npm Bower License


Installation and Use

You can download the development or production (minified) script, or install it using NPM or Bower.


npm install indexeddbshim


bower install IndexedDBShim

Using the polyfill

Add the script to your page

<script src="dist/indexeddbshim.min.js"></script>

If the browser already natively supports IndexedDB, then the script won't do anything. Otherwise, it'll add the IndexedDB API to the browser. Either way, you can use IndexedDB just like normal.

// Open (or create) the database
var open ="MyDatabase", 1);

// Create the schema
open.onupgradeneeded = function() {
    var db = open.result;
    var store = db.createObjectStore("MyObjectStore", {keyPath: "id"});
    var index = store.createIndex("NameIndex", ["name.last", "name.first"]);

open.onsuccess = function() {
    // Start a new transaction
    var db = open.result;
    var tx = db.transaction("MyObjectStore", "readwrite");
    var store = tx.objectStore("MyObjectStore");
    var index = store.index("NameIndex");

    // Add some data
    store.put({id: 12345, name: {first: "John", last: "Doe"}, age: 42});
    store.put({id: 67890, name: {first: "Bob", last: "Smith"}, age: 35});

    // Query the data
    var getJohn = store.get(12345);
    var getBob = index.get(["Smith", "Bob"]);

    getJohn.onsuccess = function() {
        console.log(;  // => "John"

    getBob.onsuccess = function() {
        console.log(;   // => "Bob"

    // Close the db when the transaction is done
    tx.oncomplete = function() {

Overriding Native IndexedDB

Even if a browser natively supports IndexedDB, you may still want to use this shim instead. Some native IndexedDB implemenatations are very buggy. Others are missing certain features.

There are also many minor inconsistencies between different browser implementations of IndexedDB, such as how errors are handled, how transaction timing works, how records are sorted, how cursors behave, etc. Using this shim will ensure consistent behavior across all browsers.

To force IndexedDBShim to replace the browser's native IndexedDB, add this line to your script:



The IndexedDB polyfill has sourcemaps enabled, so the polyfill can be debugged even if the minified file is included.

To print out detailed debug messages, add this line to your script:


Known Issues

All code has bugs, and this project is no exception. If you find a bug, please let us know about it. Or better yet, send us a fix! Please make sure someone else hasn't already reported the same bug though.

There are a few bugs that are outside of our power to fix. Namely:


Due to a bug in WebKit, the window.indexedDB property is read-only and cannot be overridden by IndexedDBShim. There are two possible workarounds for this:

  1. Use window.shimIndexedDB instead of window.indexedDB
  2. Create an indexedDB variable in your closure By creating a variable named indexedDB, all the code within that closure will use the variable instead of the window.indexedDB property. For example:
(function() {
    // This works on all browsers, and only uses IndexedDBShim as a final fallback 
    var indexedDB = window.indexedDB || window.mozIndexedDB || window.webkitIndexedDB || window.msIndexedDB || window.shimIndexedDB;

    // This code will use the native IndexedDB, if it exists, or the shim otherwise"MyDatabase", 1);

Windows Phone

IndexedDB on Windows Phone requires the Cordova WebSql plug-in, which has some known bugs. Specifically, because the WebSql plug-in is synchronous instead of asynchronous, the performance can be very poor. It can also cause stack-overflow errors when performing many operations in a single transaction. The only workaround for now is to limit yourself to no more than 10 operations per transaction.


To build the project locally on your computer:

  1. Clone this repo
    git clone

  2. Install dev dependencies
    npm install

  3. Run the build script
    npm start

  4. Done
    The output files will be generated in the dist directory


Automated Unit Tests

Follow all of the steps above to build the project, then run npm test to run the unit tests. The tests are run in PhantomJS, which is a headless WebKit browser.

Testing in a Browser

If you want to run the tests in a normal web browser. Then you'll need to spin-up a local web server and then open test/index.html and/or tests/index.html in your browser.

Testing in a Cordova/PhoneGap app

If you want to run the tests in a Cordova or PhoneGap app, then you'll need to create a new Cordova/PhoneGap project, and add the IndexedDB plug-in. Then copy the contents of our tests directory into your project's www directory. Delete our index.html file and rename cordova.html to index.html.


Pull requests or Bug reports welcome !!

Something went wrong with that request. Please try again.