Apache PouchDB: the JavaScript database that syncs to CouchDB

Who PouchDB is for, and the problem it was created to solve

The README states the goal plainly: PouchDB was created to help web developers build applications that work as well offline as they do online. That is a narrower brief than "a JavaScript database". The interesting part is not storage in the browser, which IndexedDB already provides, but replication. A PouchDB instance in a browser tab and a CouchDB instance on a server speak the same replication protocol, so a user can write records on a plane, close the laptop, and have those records land on the server the next time the app has a connection. The unit of exchange is the document, and the conflict model is the one CouchDB uses.

The target reader is a web developer building an application where the network is unreliable or the user is frequently disconnected: field data collection, note-taking, point-of-sale, anything with a mobile or kiosk client. If your app is a dashboard that reads from a server and never writes locally, PouchDB adds a storage layer and a sync layer you will not use. The homepage is https://pouchdb.com/ and the API documentation lives at https://pouchdb.com/api.html, which is where the README sends you rather than repeating API detail in the repository root.

How replication actually works between a browser and CouchDB

The mechanism visible in the repository is document-level replication against a CouchDB-compatible endpoint. PouchDB is described as inspired by Apache CouchDB, and the topics list on the repository includes couchdb alongside database and javascript. The practical consequence is that the server side is not something PouchDB invents: it is CouchDB, or a service that implements the same replication API.

That design decision carries the project's main trade-off. Because replication is CouchDB's protocol, you inherit CouchDB's conflict model, where two devices editing the same document produce a conflict that the application resolves rather than a lock that prevents the second write. For offline-first apps this is usually the right answer, since refusing writes while disconnected is not an option. For apps that need strict transactional consistency across related records, it is a poor fit, and no amount of configuration changes that.

The repository is a monorepo. The top-level package.json is named pouchdb-monorepo, is marked private, and carries scripts that build modules, run unit tests under mocha, run integration and performance tests through browserify, and build the documentation site with eleventy. Individual packages live under packages/node_modules/, which is where the README says the browser build lands after a source build. If you are reading the source rather than installing the published package, that layout is the map.

Building PouchDB from source and what lands in the dist folder

The README gives one concrete set of commands, and it is aimed at prerelease builds rather than at consumers. It says that if you like to live on the bleeding edge, you can build PouchDB from source using these steps:

git clone https://github.com/pouchdb/pouchdb.git
cd pouchdb
npm install

After running these steps, the README states that the browser build can be found in packages/node_modules/pouchdb/dist/pouchdb.js. That path is the thing to check after npm install finishes; if the file is not there, the build did not complete.

For ordinary application use, the README does not give an install command at all. It sends you to the website at https://pouchdb.com and the API documentation at https://pouchdb.com/api.html to get started, and the npm badge in the README names the published package as pouchdb. That badge is the only pointer the repository root gives toward consuming PouchDB as a dependency rather than building it.

The monorepo scripts in the top-level package.json are for working on PouchDB itself: build-modules runs node bin/build-modules.js, test-unit runs mocha against tests/unit, and build-test produces the browserify bundles for the integration and performance suites. None of those are commands an application developer needs.

Where PouchDB is the wrong tool

The README is explicit about the server role: PouchDB is designed to run well within the browser, and the CouchDB comparison in the documentation is what people search for when they are deciding between the two. If you need a database that many server processes write to concurrently, PouchDB is not that. It is a client library, and the multi-writer story is replication, not shared storage.

Storage limits are the second constraint. In a browser, PouchDB is bounded by what the browser grants the origin, and a large local dataset will hit that ceiling. The repository ships a memory-leak test target, which tells you the maintainers take long-running browser sessions seriously, but it does not tell you the ceiling is high.

The third case is query shape. PouchDB's data model is documents, and the repository includes a pouchdb-find plugin referenced in the coverage script. If your application is built around joins, foreign keys and ad-hoc aggregation, a document store with a find plugin is a mismatch, and you will spend more effort reshaping queries than you would have spent choosing a relational engine. Nothing in the repository suggests PouchDB is trying to be that engine.

PouchDB compared with SQLite and IndexedDB

The two alternatives people search for most often are SQLite and IndexedDB, and the difference is architectural rather than a matter of taste. IndexedDB is a browser storage API. It gives you object stores, transactions and indexes, and it stops there: there is no replication protocol, no conflict resolution, and no server counterpart. If you build on IndexedDB directly, you write the sync layer yourself. PouchDB sits above browser storage and adds the CouchDB replication model, which is the entire value it contributes.

SQLite is the opposite trade. It is a relational engine with SQL, joins and a mature query planner, and it runs in the browser through WebAssembly builds and on the server as a file-backed database. It is the better choice when your data is relational and your queries are analytical. It is the weaker choice when the requirement is that a browser and a server converge on the same documents after a period of disconnection, because that convergence is not SQLite's job.

The honest summary is that these are not competing answers to one question. If you want a local relational store, take SQLite. If you want a local document store that reconciles with a CouchDB server, take PouchDB. Choosing PouchDB for relational workloads and then complaining about query ergonomics is a decision error, not a defect.

Project status, licence and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-13. The most recent release listed is 9.0.0, published on 2024-06-21, following 8.0.1 on 2023-02-09 and 8.0.0 on 2022-12-15. The gap between the newest release and repository activity is worth noticing: commits continue while tagged releases are spaced by more than a year, so if you depend on release cadence rather than on master, plan around that rhythm.

The README states that PouchDB is currently undergoing Incubation at the Apache Software Foundation and points to the DISCLAIMER file for incubator projects. That is a governance fact, not a stability claim, and the DISCLAIMER is the file to read before you make assumptions either way. The licence is Apache-2.0, declared in both the repository metadata and the package.json. Apache-2.0 permits commercial use and modification and includes a patent grant; it also requires that you preserve notices. This is a description of the licence text, not legal advice, and if you are redistributing a modified PouchDB you should have counsel read the NOTICE and LICENSE files that ship in the repository.

Upgrade cost is unusually low by the project's own account. The README states that PouchDB is auto-migrating, so a database created in 1.0.0 will still work if you open it in 4.0.0 or later, and that any release containing a migration is clearly marked in the release notes. That is a strong compatibility promise, and it means the main upgrade risk is API change rather than data migration. The README points to a wiki list of breaking changes for a concise view, and that list is what you should read before crossing a major version. Because the repository is a monorepo with its own build, test and release scripts, contributors should expect to run the documented build and test tooling rather than a single npm test.

Editorial conclusion

Adopt PouchDB when the app must keep working offline and the server side is already CouchDB or CouchDB-compatible, because replication is the reason the project exists and the README states that PouchDB is auto-migrating, so a database created in 1.0.0 still opens in 4.0.0 and later. Do not adopt it as a general-purpose server database or as a relational store; the README points to CouchDB for the server role and the repository carries no SQL layer. Before committing, verify the ASF incubator disclaimer in the DISCLAIMER file, confirm which version the npm package resolves to, and check the wiki list of breaking changes for the range you are crossing.

Frequently asked questions

Official sources

1. apache/pouchdb on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases