{"id":16499,"library":"pouchdb","title":"PouchDB","description":"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.","status":"active","version":"9.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/pouchdb/pouchdb","tags":["javascript","db","couchdb","pouchdb"],"install":[{"cmd":"npm install pouchdb","lang":"bash","label":"npm"},{"cmd":"yarn add pouchdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add pouchdb","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const PouchDB = require('pouchdb');","symbol":"PouchDB","correct":"import PouchDB from 'pouchdb';"},{"note":"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.","wrong":"import { PouchDB } from 'pouchdb-browser';","symbol":"PouchDB (browser-only build)","correct":"import PouchDB from 'pouchdb-browser';"},{"note":"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.","wrong":"import { plugin } from 'pouchdb';\nPouchDB.plugin(require('pouchdb-adapter-indexeddb'));","symbol":"PouchDB.plugin","correct":"import PouchDB from 'pouchdb';\nimport pouchdbAdapterIndexedDB from 'pouchdb-adapter-indexeddb';\nPouchDB.plugin(pouchdbAdapterIndexedDB);"}],"quickstart":{"code":"import PouchDB from 'pouchdb';\n\nasync function initializeAndUseDB() {\n  // Open or create a database named 'my_local_db'\n  // In browsers, this defaults to IndexedDB. In Node.js, it uses LevelDB.\n  const db = new PouchDB('my_local_db');\n  console.log('Database opened successfully!');\n\n  try {\n    // Create a new document\n    const newDoc = {\n      _id: 'dave@example.com',\n      name: 'David Z.',\n      occupation: 'Developer',\n      age: 30\n    };\n    const response = await db.put(newDoc);\n    console.log('Document created:', response);\n\n    // Fetch the document\n    const fetchedDoc = await db.get('dave@example.com');\n    console.log('Document fetched:', fetchedDoc);\n\n    // Update the document\n    fetchedDoc.age = 31;\n    const updateResponse = await db.put(fetchedDoc);\n    console.log('Document updated:', updateResponse);\n\n    // Delete the database (for cleanup or testing)\n    // await db.destroy();\n    // console.log('Database destroyed.');\n\n  } catch (err) {\n    console.error('Error interacting with PouchDB:', err);\n  }\n}\n\ninitializeAndUseDB();","lang":"javascript","description":"Demonstrates how to install PouchDB, create a new local database, add, retrieve, and update documents using the async/await pattern."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=9.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=8.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=7.2.2"},{"fix":"If your application relies on WebSQL, you must explicitly include the `pouchdb-adapter-websql` plugin. Consider migrating to IndexedDB for modern browser support.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"PouchDB couldn't find a suitable storage adapter for the environment.","error":"Uncaught Error: Adapter is not installed. Did you remember to add pouchdb-adapter-idb or pouchdb-adapter-websql?"},{"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.","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.","error":"TypeError: PouchDB is not a constructor"},{"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.","cause":"Using CommonJS `require()` syntax in a browser environment without a bundler, or in a pure ES module context in Node.js.","error":"ReferenceError: require is not defined"},{"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.","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.","error":"Error: Cannot use \"indexeddb\" adapter without manual data migration from \"idb\" (legacy)"}],"ecosystem":"npm"}