PouchDB is not a self-contained database; it is a CouchDB-style abstraction layer over other databases. By default, PouchDB ships with IndexedDB and WebSQL adapters in the browser, and a LevelDB adapter in Node.js.
PouchDB attempts to provide a consistent API that "just works" across every browser and JavaScript environment, and in most cases, you can just use the defaults. However, if you're trying to reach the widest possible audience, or if you want the best performance, then you will sometimes want to tinker with the adapter settings.
Topics:
In the browser, PouchDB prefers IndexedDB, and falls back to WebSQL if IndexedDB is not available. As of 2015, the browser support looks like this:
Desktop
![]() |
![]() |
![]() |
![]() |
![]() |
|
---|---|---|---|---|---|
Adapter | IE | Firefox | Chrome | Safari | Opera |
IndexedDB | ✓ (10+) | ✓ | ✓ | ✓ | |
WebSQL | ✓ | ✓ | ✓ |
Mobile
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
|
---|---|---|---|---|---|---|---|---|
Adapter | iOS Safari | Opera Mini | Android Browser | BlackBerry Browser | Opera Mobile | Chrome for Android | Firefox for Android | IE Mobile |
IndexedDB | ✓ (4.4+) | ✓ (10+) | ✓ (21+) | ✓ | ✓ | ✓ | ||
WebSQL | ✓ | ✓ | ✓ | ✓ | ✓ | |||
If you're ever curious which adapter is being used in a particular browser, you can use the following method:
var pouch = new PouchDB('myDB');
console.log(pouch.adapter); // prints either 'idb' or 'websql'
SQLite plugin for Cordova/PhoneGap
On Cordova/PhoneGap, the native SQLite database is often a popular choice, because it allows unlimited storage (compared to IndexedDB/WebSQL storage limits). It also offers more flexibility in backing up and pre-loading databases, because the SQLite files are directly accessible to app developers.
Luckily, there is a SQLite Plugin (also known as SQLite Storage) that accomplishes exactly this. If you include this plugin in your project, then PouchDB will automatically pick it up based on the window.sqlitePlugin
object.
However, this only occurs if the adapter is 'websql'
, not 'idb'
(e.g. on Android 4.4+). To force PouchDB to use the WebSQL adapter, you can do:
var db = new PouchDB('myDB', {adapter: 'websql'});
If you are unsure whether PouchDB is using the SQLite Plugin or not, just run:
db.info().then(console.log.bind(console));
This will print some database information, including the attribute sqlite_plugin
, which will be true
is the SQLite Plugin is being used.
The SQLite Plugin is known to pass the PouchDB test suite on both iOS and Android, although Windows Phone 8 is untested. Note that the SQLite Plugin code changes frequently, and is not tested in PouchDB’s automated test suite.
Furthermore, you may experience slower performance with the SQLite Plugin than with IndexedDB/WebSQL, due to the cost of serializing data between JavaScript and the native code.
Browser adapter plugins
PouchDB also offers separate browser plugins that use backends other than IndexedDB and WebSQL. These plugins fully pass the PouchDB test suite and are rigorously tested in our CI process.
Downloads:
- pouchdb.localstorage.js (Minified: pouchdb.localstorage.min.js)
- pouchdb.memory.js (Minified: pouchdb.memory.min.js)
- pouchdb.idb-alt.js (Minified: pouchdb.idb-alt.min.js)
These plugins add a hefty footprint due to external dependencies, so take them with a grain of salt. You may want to use the Browserify/Webpack versions to deduplicate code and create a smaller bundle.
LocalStorage adapter
If you need to support very old browsers, such as IE ≤ 9.0 and Opera Mini, you can use the pouchdb.localstorage.js
plugin, which allows PouchDB to fall back to LocalStorage on browsers that don't support either IndexedDB or WebSQL. The es5-shims will also be necessary.
<script src="pouchdb.js"></script>
<script src="pouchdb.localstorage.js"></script>
<script>
// this pouch is backed by LocalStorage
var pouch = new PouchDB('mydb', {adapter: 'localstorage'});
</script>
In-memory adapter
If you want a quick database for your unit tests, you can use the pouchdb.memory.js
plugin, which offers a pure in-memory PouchDB:
<script src="pouchdb.js"></script>
<script src="pouchdb.memory.js"></script>
<script>
// this pouch is ephemeral; it only exists in memory
var pouch = new PouchDB('mydb', {adapter: 'memory'});
</script>
This pouch will act exactly like a normal one – replicating, storing attachments, pagination, etc. – but it will be deleted as soon as the user closes their browser. However, multiple PouchDB
objects with the same database name will share the same data:
// pouch1 and pouch2 will share the same data
var pouch1 = new PouchDB('myDB', {adapter: 'memory'});
var pouch2 = new PouchDB('myDB', {adapter: 'memory'});
// pouch3 will have its own data
var pouch3 = new PouchDB('myOtherDB', {adapter: 'memory'});
Alternative IndexedDB adapter
We are currently experimenting with a LevelDOWN-based IndexedDB adapter (using level-js) which may eventually replace the current IndexedDB adapter. If you would like to experiment with this, you may use the pouchdb.idb-alt.js
plugin:
<script src="pouchdb.js"></script>
<script src="pouchdb.idb-alt.js"></script>
<script>
// this pouch is backed by IndexedDB but uses
// a different structure than the main one
var pouch = new PouchDB('mydb', {adapter: 'idb-alt'});
</script>
This adapter does not currently offer any advantages over the 'idb'
adapter, but PouchDB developers will be interested in testing it.
In Node.js, the adapter situation is much simpler than in browsers. By default, if you create a PouchDB like this one:
var pouch = new PouchDB('./path/to/db');
then a LevelDB-based database will be created in the directory ./path/to/db
.
Plus, since the LevelDB adapter is based on LevelDOWN, you also benefit from the rich ecosystem of LevelDOWN-based adapters. They may be installed using plain old npm install
and require()
. Below are a few examples.
In-memory
Just as in the browser, you can create a pure in-memory pouch based on MemDOWN:
$ npm install memdown
then:
var pouch = new PouchDB('myDB', {db: require('memdown')});
Notice that in Node.js, we use the key 'db'
instead of 'adapter'
. In Node.js the adapter is always called 'leveldb'
for historical reasons.
Riak-based adapter
This pouch is backed by RiakDOWN:
$ npm install riakdown
then:
var pouch = new PouchDB('riak://localhost:8087/somebucket', {db: require('riakdown')});
More LevelDOWN adapters
There are many other LevelDOWN-based plugins – far too many to list here. You can find a mostly-complete list on Github that includes implementations on top of MySQL, Windows Azure Table Storage, and SQLite.
In both the browser and in Node.js, PouchDB can also function as a straightforward API on top of any CouchDB-compliant database:
var pouch = new PouchDB('http://my-site.com:5984/my-db');
var securePouch = new PouchDB('https://my-secure-site.com:5984/my-secure-db');
You can also sync to and from these databases to your local PouchDB.
Currently PouchDB has full support for:
- CouchDB 1.x (tested in CI)
- IrisCouch (same as 1.x)
- Couchappy (same as 1.x)
- CouchDB 2.x (tested in CI)
- Cloudant (roughly the same as 2.x)
- PouchDB Server (tested in CI)
- PouchDB Server --in-memory mode (tested in CI)
Couchbase Sync Gateway support is in progress. It will work, but you may run into issues, especially with attachments. Drupal 8 has also announced support for PouchDB, and there is rcouch as well, but these are both untested by PouchDB.
If you are ever unsure about a server, consider replicating from PouchDB to CouchDB, then from that CouchDB to the other server.
PouchDB Server
PouchDB Server is a standalone REST server that implements the CouchDB API, while using a LevelDB-based PouchDB under the hood. It also supports an --in-memory
mode and any LevelDOWN adapter, which you may find handy.
PouchDB Server passes the PouchDB test suite at 100%, but be aware that it is not as full-featured or battle-tested as CouchDB.
PouchDB Express
The underlying module for PouchDB Server, Express PouchDB is an Express submodule that mimics most of the CouchDB API within your Express application.
The best place to look for information on which browsers support which databases is caniuse.com. You can consult their tables on browser support for various backends: