pouchdb

library9.0.0jsnpmunverified

PouchDB is an open-source JavaScript database designed for offline-first web applications, enabling data storage directly in the user's browser (or Node.js environment) and seamless synchronization with CouchDB-compatible servers. Currently at stable version 9.0.0 (released May 24, 2024), the project releases major versions periodically, with patch releases addressing bugs and minor enhancements more frequently. Its key differentiators include its robust replication engine, automatic offline data handling, and its ability to work across various browser and Node.js environments without requiring a persistent network connection, providing a highly resilient and performant user experience even without network connectivity.

database

npm install pouchdb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POUCHDB

pouchdb

databasejavascriptv9.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PouchDB

✓ import PouchDB from 'pouchdb';

✗ const PouchDB = require('pouchdb');

While CommonJS `require` works, PouchDB has been progressively moving to modern ES6+ syntax since v8.0.0 (released Dec 14, 2022). ESM `import` is the recommended pattern, especially for browser-side bundling.

PouchDB (browser-only build)

✓ import PouchDB from 'pouchdb-browser';

✗ import { PouchDB } from 'pouchdb-browser';

For browser-specific applications, `pouchdb-browser` is a smaller preset that includes IndexedDB (default) and WebSQL adapters, and excludes Node.js-specific code (like LevelDB). It's typically imported as a default export.

PouchDB.plugin

✓ import PouchDB from 'pouchdb'; import pouchdbAdapterIndexedDB from 'pouchdb-adapter-indexeddb'; PouchDB.plugin(pouchdbAdapterIndexedDB);

✗ import { plugin } from 'pouchdb'; PouchDB.plugin(require('pouchdb-adapter-indexeddb'));

Adapters and plugins are added via the `PouchDB.plugin()` method. Ensure the plugin itself is imported correctly, typically as a default export, and then passed to the plugin method. For older CJS usage, `require('pouchdb-adapter-indexeddb')` directly inside `plugin()` was common.

Demonstrates how to install PouchDB, create a new local database, add, retrieve, and update documents using the async/await pattern.

import PouchDB from 'pouchdb'; async function initializeAndUseDB() { // Open or create a database named 'my_local_db' // In browsers, this defaults to IndexedDB. In Node.js, it uses LevelDB. const db = new PouchDB('my_local_db'); console.log('Database opened successfully!'); try { // Create a new document const newDoc = { _id: 'dave@example.com', name: 'David Z.', occupation: 'Developer', age: 30 }; const response = await db.put(newDoc); console.log('Document created:', response); // Fetch the document const fetchedDoc = await db.get('dave@example.com'); console.log('Document fetched:', fetchedDoc); // Update the document fetchedDoc.age = 31; const updateResponse = await db.put(fetchedDoc); console.log('Document updated:', updateResponse); // Delete the database (for cleanup or testing) // await db.destroy(); // console.log('Database destroyed.'); } catch (err) { console.error('Error interacting with PouchDB:', err); } } initializeAndUseDB();

Debug

Known issues

breakingPouchDB 9.0.0 introduces a default limit of 25 to the `.find()` method, which is a backwards-incompatible change. It also includes other internal refactors and improvements to the IndexedDB adapter's stability and performance.

fix

Review `.find()` queries and explicitly set `limit: false` or a higher `limit` value if you expect more than 25 results, or adjust your application logic to handle pagination. Consult the official 9.0.0 changelog for other potential breaking changes.

affects: >=9.0.0

breakingPouchDB 8.0.0 began a significant refactor to embrace modern ES6+ JavaScript syntax, utilizing native JS classes instead of prototypes. This can lead to compatibility issues with older build tools, Node.js versions, or environments expecting CommonJS prototypes.

fix

Ensure your project uses a modern JavaScript environment (Node.js 14+ recommended as per 8.0.1 release) and a transpiler like Babel if targeting older environments. Update bundler configurations to correctly handle ES modules.

affects: >=8.0.0

breakingPouchDB 7.2.2 introduced a new 'indexeddb' adapter that uses native indexes. This new adapter is NOT backwards compatible with data stored using the older 'idb' adapter, and data migration is a manual process left to the developer.

fix

If migrating an existing application, plan for a data migration strategy from 'idb' to 'indexeddb'. For new applications, explicitly specify `{ adapter: 'indexeddb' }` if you intend to use the newer, more performant adapter.

affects: >=7.2.2

breakingStarting with PouchDB 7.0.0 (released June 21, 2018), the WebSQL adapter was removed from the default builds to reduce package size and focus development efforts. It is no longer included by default.

fix

If your application relies on WebSQL, you must explicitly include the `pouchdb-adapter-websql` plugin. Consider migrating to IndexedDB for modern browser support.

affects: >=7.0.0

gotchaPouchDB is an abstraction layer that requires an underlying storage adapter. While the main `pouchdb` package includes default adapters (IndexedDB in browser, LevelDB in Node.js), certain environments or specific needs might require explicit adapter installation and plugin registration.

fix

Always verify which adapter is being used in your target environment. If using a specific adapter (e.g., `pouchdb-adapter-memory`), ensure it's installed and registered via `PouchDB.plugin(adapter)`.

affects: All versions

Errors

Common errors & fixes

Uncaught Error: Adapter is not installed. Did you remember to add pouchdb-adapter-idb or pouchdb-adapter-websql?

PouchDB couldn't find a suitable storage adapter for the environment.

fix

Install and register the appropriate adapter (e.g., `npm install pouchdb-adapter-indexeddb` then `PouchDB.plugin(PouchdbAdapterIndexedDB);`) or use a preset like `pouchdb-browser` which includes adapters.

TypeError: PouchDB is not a constructor

Attempting to instantiate PouchDB incorrectly, often due to CommonJS vs. ES module import mismatch, or trying to access it via a named import when it's a default export.

fix

For ES Modules, use `import PouchDB from 'pouchdb';`. For CommonJS (older Node.js), use `const PouchDB = require('pouchdb');`. Avoid destructuring for the main `PouchDB` constructor.

ReferenceError: require is not defined

Using CommonJS `require()` syntax in a browser environment without a bundler, or in a pure ES module context in Node.js.

fix

If in a browser, use a bundler (Webpack, Rollup) to transpile CommonJS, or use the pre-built browser-friendly bundles. If in a Node.js ES module, switch to `import` statements.

Error: Cannot use "indexeddb" adapter without manual data migration from "idb" (legacy)

Trying to open a database created with the old 'idb' adapter using the newer 'indexeddb' adapter without migrating data, as of PouchDB 7.2.2.

fix

Implement a manual data migration process to move data from databases created with the 'idb' adapter to the 'indexeddb' adapter, or stick to the 'idb' adapter if backward compatibility with existing data is critical and you don't need the new features/performance.

Upgrade

Version history

9.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/pouchdb/pouchdb ↗

packagehttps://www.npmjs.com/package/pouchdb ↗

homepagehttps://pouchdb.com ↗