Apache PouchDB

PouchDB is a JavaScript implementation of CouchDB designed to run in the browser or in Node.js. Its primary goal is to emulate the CouchDB API with near-perfect fidelity.

Key characteristics include:

• Web-Native: It uses HTTP as its primary means of communication, allowing you to interact with the database using standard REST and HTTP without special drivers.
• Synchronization: It is designed for easy synchronization (replication) between different databases. PouchDB specifically enables this by running the database directly inside the client's browser.
• Interoperability: Because it follows the CouchDB sync protocol, PouchDB can sync with CouchDB, Cloudant, and Couchbase.

PouchDB capabilities are available beyond standard web environments:

• Go / GopherJS: Kivik provides a common interface to CouchDB-like databases, including a PouchDB driver.
• Python: Python-PouchDB provides both synchronous and asynchronous APIs using QtWebKit.
• Android: PouchDroid provides an Android adapter with a native Java interface.

PouchDB supports all modern browsers and several mobile/desktop environments.

Supported Browsers

• Firefox 29+
• Chrome 30+
• Safari 5+
• Internet Explorer 10+
• Opera 21+
• Android 4.0+
• iOS 7.1+
• Windows Phone 8+

Supported Runtimes & Frameworks

• Mobile/Desktop: Cordova/PhoneGap, NW.js, Electron, and Chrome apps.
• Node.js: Uses LevelDB under the hood.
• Frameworks: Works with Angular, React, Ember, Backbone, or any other framework.

Compatibility Notes

• Legacy Browsers: For IE <10 or Android <4.0, you must include the es5-shim library to provide a modern ES5 environment.
• Alternative Storage: If IndexedDB/WebSQL are unavailable, you can use LocalStorage or in-memory adapters, or fall back to a live CouchDB.

For server-side implementations and advanced replication, consider these tools:

• PouchDB Server: A standalone REST interface server for PouchDB.
• Express PouchDB: An Express submodule providing a CouchDB-style REST interface (powers PouchDB Server).
• Websocket Sync: Pouch Websocket Sync for syncing multiple PouchDBs via websockets, and SocketPouch for replication over WebSockets using Engine.io/Socket.io.
• Streaming: Pouch Stream Server to serve generic PouchDB object streams, and Pouch Remote Stream to consume them on the client.

PouchDB 9.0.0 is a major release featuring several key improvements:

• IndexedDB Adapter: Significant improvements to stability and performance.
• .find() Method: Introduced a default limit of 25 (breaking change).
• Testing Infrastructure: Automated test suites have been streamlined, moving in-browser testing to Playwright for increased reliability.
• Modern JavaScript: Continued updates to the codebase to use ES6 standards.

PouchDB is an in-browser database designed for offline-first applications. It allows applications to save data locally so users can interact with the app without an internet connection. Data can be synchronized between clients to keep users up-to-date across devices.

Key characteristics:

• Environment Agnostic: The API is consistent whether running in a browser or in Node.js.
• CouchDB Compatible: It can act as a direct interface to CouchDB-compatible servers.
• Framework Agnostic: It can be used with any JavaScript framework (Angular, React, Ember, Backbone, etc.) or used as-is.
• Storage Backends:
  • In the browser, it uses IndexedDB (primary) or WebSQL (fallback).
  • In Node.js, it uses LevelDB (primary) and supports other backends via the LevelUP ecosystem.

PouchDB is a NoSQL database that stores unstructured documents instead of using a fixed schema with rows and tables.

SQL to PouchDB Mapping

If you are transitioning from a SQL background, use this mapping:

• Table: No equivalent
• Row: Document
• Column: Field
• Primary Key: _id
• Index: View

PouchDB supports two types of data: documents and attachments.

Documents

Documents must be serializable as JSON.

• Do not modify the Object prototype.
• Do not attempt to store classes.
• While IndexedDB might support non-JSON data (like Date objects), you should not rely on this as other backends (CouchDB, LevelDB, Web SQL) do not support it.

Attachments

Attachments are the most efficient way to store binary data and can be supplied as Blob objects or base64-encoded strings.

Storage Strategies:

• Blob: True binary format (most efficient).
• UTF-16 Blob: Coerced to UTF-16 (takes 2x space).
• Base-64: Encoded string (least efficient).

Note on Deletion: Attachments are deduplicated by MD5 sum. To fully remove an attachment from the data store, you must use [compaction] to remove the document revisions that reference it.

Avoid emitting the entire document in map/reduce functions (e.g., emit(doc.foo, doc)). This causes the entire document to be serialized and written to disk, which is inefficient. Instead, only emit() the specific values you need. If you need the full document during a query, use the {include_docs: true} option to retrieve the freshest version of the document.

// Avoid this:
function (doc) {
  emit(doc.foo, doc);
}

// Do this:
function (doc) {
  emit(doc.foo);
}
// Then use {include_docs: true} in your query

PouchDB requires a backend that implements the CouchDB replication protocol. This protocol requires all documents to be versioned with a _rev marker to handle conflicts.

Compatible databases include:

• CouchDB: The primary reference database.
• Cloudant: A cluster-aware fork of CouchDB.
• PouchDB Server: An HTTP API built on top of PouchDB. It supports backends like in-memory, Redis, Riak, and MySQL via the LevelUP ecosystem.

Note: When using PouchDB Server with alternate backends, your application must interact via the PouchDB API rather than modifying the underlying database directly.

PouchDB 6.1.1 includes fixes to better handle environments where a CouchDB server is behind a proxy server that may not strictly follow CouchDB's behavior:

• Non-live _changes requests: PouchDB no longer adds a default heartbeat parameter to changes() requests that are not configured as live: true. This prevents potential issues with proxies that do not support or expect heartbeat parameters on standard requests.
• bulkGet error handling: PouchDB now falls back from bulkGet on any error, rather than only on 4XX errors, improving robustness when proxies return unexpected error codes.