Asynchronous IndexedDB plugin for Cordova

Features

• Uses IndexedDBShim to polyfill devices that don't support IndexedDB
• Uses the asynchronous WebSql plugin on Windows devices
• Uses the cordova-plugin-sqlite-2 on iOS devices
• Can optionally replace native IndexedDB on devices with buggy implementations
• Can optionally enhance native IndexedDB on devices that are missing certain features
• This plugin is basically an IndexedDB-to-WebSql adapter

Installation

Install via the Cordova CLI.

For Cordova CLI 4.x, use the GIT URL syntax:

cordova plugin add https://github.com/hitachienergy/cordova-plugin-indexeddb-async.git

For Cordova CLI 5.x, use the new npm syntax:

cordova plugin add cordova-plugin-indexeddb-async

Using the Plugin

Cordova will automatically load the plugin and run it. So all you need to do is use IndexedDB just like normal.

Here's an example

Supported Platforms

This plugin supports ios, android, and windows (phone and desktop), as well as the new browser platform.

Android

Android 4.3 and earlier do not support IndexedDB, so this plugin will automatically add IndexedDB support. On Android 4.4 and later, the plugin does nothing, since IndexedDB is already natively supported.

Browser

All modern browsers natively support IndexedDB, so the plugin won't do anything. But for older browsers that support WebSQL, this plugin will automatically add IndexedDB support.

iOS

iOS 7 and earlier do not support IndexedDB, so this plugin will automatically add IndexedDB support. On iOS 8 and later, the plugin does nothing, since IndexedDB is already natively supported.

iOS 8's implementation of IndexedDB is very buggy. So, you may want to use this plugin rather than the native implementation. To do that, add the following line of code to your app:

window.shimIndexedDB.__useShim()

Known Issues on iOS

Due to a bug in WebKit, the window.indexedDB property is read-only and cannot be overridden by IndexedDBShim. Until the bug is fixed, the only workaround is to create an indexedDB variable in your closure. That way, all code within that closure will use the variable instead of the window.indexedDB property. For example:

(function() {
    // This works on all devices/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
    indexedDB.open("MyDatabase", 1);
})();

Another bug in webkit in the WebSQL causes memory leaks while calling openDatabase to many times. This results in a shutdown of the application. For iOS devices we now fallback to the cordova-plugin-sqlite-2 plugin.

Windows

Windows 8 and 8.1 support IndexedDB natively, so the plugin won't do anything by default.

Windows 8.x's implementation of IndexedDB is mising some features, such as compound keys and compound indexes. If you need those features in your app, then you may want to use this plugin rather than the native implementation. To do that, add the following line of cose to your app:

window.shimIndexedDB.__useShim()

Windows Phone

Windows Phone does not support IndexedDB or WebSQL, so this plugin will automatically load the asynchronous WebSQL plugin to add WebSQL support, and then use IndexedDBShim to expose WebSQL to your app via the IndexedDB API. It's complicated, but it works. :)

The WebSQL plugin is specifically written for Windows Phone, so it only supports the two processor architectures that Windows Phone supports (x86 and arm). This means that you need to specify an extra flag when building your Windows Phone app via Cordova:

cordova build windows --archs="x86 arm" -- --phone