PouchDB

Common errors

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

  cause 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

  cause 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

  cause 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)

  cause 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.

Warnings

• breaking PouchDB 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.
• breaking PouchDB 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.
• breaking PouchDB 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.
• breaking Starting 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.
• gotcha PouchDB 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)`.

Install

• npm install pouchdb npm
• yarn add pouchdb yarn
• pnpm add pouchdb pnpm

Imports

• PouchDB
  wrong:

  const PouchDB = require('pouchdb');

  correct:

  import PouchDB from '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)
  wrong:

  import { PouchDB } from 'pouchdb-browser';

  correct:

  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
  wrong:

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

  correct:

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

  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.

Quickstart

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();