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.
- Couchbase Sync Gateway – A sync gateway for Couchbase.
- 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.
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 Exporer 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
iOS Web Application, a page saved on the homescreen behaves different 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 behaviour 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).
For more information, see Working with quota on mobile browsers.
PouchDB has two types of data: documents and attachments.
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.
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
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:
|Adapter||IE (10+)||Firefox||Chrome < 43,
|Chrome >= 43||Safari < 7.1,
iOS < 8
|Safari < 10.1, >= 7.1,
iOS < 10.3, >= 8
|Safari >= 10.1,
iOS >= 10.3
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.