FAQ

No, your backend needs to speak the CouchDB replication protocol. The magic of PouchDB <–> CouchDB sync comes from this design, which in particular requires all documents to be versioned with the _rev marker. This allows PouchDB and CouchDB to elegantly handle conflicts, among other benefits.

There are a number of databases that implement a CouchDB-like protocol, and PouchDB should be able to replicate with them. They include:

• CouchDB – CouchDB is our primary reference database and is used for automated testing.
• Cloudant – A cluster-aware fork of CouchDB.
• PouchDB Server – An HTTP API written on top of PouchDB. Additionally, it supports alternate backends like in-memory, Redis, Riak and MySQL via the LevelUP ecosystem. Note that your application must use the PouchDB API rather than directly modifying the database, however.

PouchDB is one of multiple projects that implement the CouchDB protocol, and these can all be used to sync the same set of data.

For desktop applications, you may want to look into embedding CouchDB (or rcouch). PouchDB also works great with web-based frameworks like node-webkit, Chrome apps, Electron and WinJS.

For mobile applications, you can use PouchDB within PhoneGap/Cordova (optionally using the SQLite Plugin), or there are several native libraries:

iOS:

• Couchbase Lite for iOS
• Cloudant Sync for iOS

Android:

• Couchbase Lite for Android
• Cloudant Sync for Android

In Firefox, PouchDB uses IndexedDB. Though Firefox has no upper limit besides disk space, if your application wishes to store more than 50MB locally, Firefox will ask the user using a non-modal dialog to confirm that this is okay.

Chrome also uses IndexedDB, and it determines the amount of storage available on the user’s hard drive and uses that to calculate a limit.

Opera 15+ shares a codebase with Chromium/Blink, and behaves similarly.

Internet Explorer 10+ has a hard 250MB limit, and will prompt the user with a non-modal dialog at 10MB.

Mobile Safari on iOS has a hard 50MB limit for WebSQL, whereas desktop Safari has no limit. Both will prompt the user with a modal dialog if an application requests more than 5MB of data, at increments of 5MB, 10MB, 50MB, 100MB, etc. Some versions of Safari have a bug where they only let you request additional storage once, so you'll need to request the desired space up-front. PouchDB allows you to do this using the size option.

iOS Web Application, a page saved on the homescreen behaves differently than apps in Mobile Safari (at least from iOS 9.3.2+). No specifics are published online by Apple, but WebSQL storage seems not limited to 50mb and there will not be any prompts when requesting data storage. Use <meta name="apple-mobile-web-app-capable" content="yes"> in your html header and use Add to Home Screen in the share menu of Safari. Please note, IndexedDB is now available as of iOS 10.3. It seems there is different behavior for different models of iPad and iPhone. You can check your mileage using the storage abuser, which you can Add to Home Screen on your device. Caveat: when iOS is running low on storage space, the OS might decide to delete all data without any notice or warning to the end user. Be sure to use devices with plenty of spare space, or your users will lose unsynced data.

Android works the same as Chrome as of 4.4+ (IndexedDB), while older versions can store up to 200MB (WebSQL).

In PhoneGap/Cordova, you can have unlimited data on both iOS and Android by using the SQLite Plugin.

For more information, see Working with quota on mobile browsers.

PouchDB has two types of data: documents and attachments.

Documents

As in CouchDB, the documents you store must be serializable as JSON. Modifying the Object prototype or storing classes is not supported.

IndexedDB will actually support non-JSON data (e.g. Dates aren't stringified), but you should not rely on this, because CouchDB, LevelDB, and Web SQL do not behave the same.

Attachments

PouchDB also supports attachments, which are the most efficient way to store binary data. Attachments may either be supplied as base64-encoded strings or as Blob objects.

Different backends have different strategies for storing binary data, which may affect the overall database size. Attachment stubs have a length property that describes the number of bytes in the Blob object, but under the hood, it may actually take up more space than that.

PouchDB's strategies are:

• Blob: data is stored in a true binary format. The most efficient method.
• UTF-16 Blob: blobs are coerced to UTF-16, so they takes up 2x the normal space.
• Base-64: data is stored as a base-64-encoded string. The least efficient method.

Here are the strategies used by various browsers in PouchDB:

Attachments are deduplicated based on their MD5 sum, so duplicate attachments won't take up extra space.

To truly remove an attachment from the data store, you will need to use compaction to remove document revisions that reference that attachment.

Since v1.0.0, PouchDB has supported automatic schema migrations. This means that if you open a database that was built with an older version of PouchDB, the newer version will run all the steps necessary to get the old database up to date. We have extensive tests in place to guarantee that this feature works correctly.

Even in the case of a major version release, PouchDB still performs the schema migrations. So for instance, you can create a database with PouchDB 1.0.0 and it will still work after you open it in 3.0.0.

Once a database is migrated, however, you can no longer open it with an older version of PouchDB. So if an update contains a migration, it will be clearly marked in the release notes.

PouchDB is also a CouchDB client, and you should be able to switch between a local database or an online CouchDB instance without changing any of your application's code.

However, there are some minor differences to note:

View Collation - CouchDB uses ICU to order keys in a view query; in PouchDB they are ASCII ordered.

View Offset - CouchDB returns an offset property in the view results. In PouchDB, offset just mirrors the skip parameter rather than returning a true offset.