PouchDB for PhoneGap/Cordova
Latest commit f05cd2a Feb 4, 2015 @nolanlawson update readme
Permalink
Failed to load latest commit information.
README.md update readme Feb 4, 2015

README.md

pouchdb-phonegap-cordova

PouchDB runs great on PhoneGap and Cordova. Here's how to get started.

Sample apps

Installation

Just download pouchdb.js and include it in your index.html:

<script src="./path/to/pouchdb.js"></script>

By default, PouchDB will use either WebSQL or IndexedDB – whatever is available on the device. PouchDB supports:

Platform Supported version
Android 4+
iOS 7+
Windows Phone 8+
Firefox OS all
BlackBerry 10+

Android 2.3 and Windows Phone 7 are not supported.

SQLite Plugin

The Cordova SQLite Plugin provides a WebSQL-like API that gives direct access to the same SQLite API used by native apps.

You may want it for a few reasons:

  • To avoid storage limits.
  • To run in a background thread instead of the UI thread (e.g. if the UI slows down).
  • To use SQLite on Windows Phone 8 (instead of IndexedDB).
  • To provide more direct control over the SQLite database (e.g. so you can prepopulate the database using native code).

It's recommended to avoid the SQLite Plugin unless you really need it, since it adds extra complexity and may actually be slower (due to context switching between native code and JavaScript).

But if you do need it, here's what you should do:

First, be sure to include pouchdb.js after cordova.js and/or SQLitePlugin.js, so that PouchDB will know to wait for the 'ondeviceready' event and use the SQLite Plugin:

<script src="cordova.js"></script>
<script src="SQLitePlugin.js"></script>
<script src="./path/to/pouchdb.js"></script>

Second, create a PouchDB that prefers WebSQL to IndexedDB (rather than the reverse, which is the default). You can use this code:

var db = new PouchDB('my_database', {adapter: 'websql'});
if (!db.adapter) {
  // websql/sqlite not supported (e.g. FirefoxOS)
  db = new PouchDB('my_database');
}

The adapter is called 'websql', but as long as you have the SQLite Plugin installed (i.e. you have navigator.sqlitePlugin or window.sqlitePlugin available as global variables), then PouchDB will use the SQLite Plugin.

See the sample apps above if you get stuck.