PouchDB Replicator Plugin

Common errors

• TypeError: PouchDB.plugin is not a function

  cause The PouchDB library was either not imported, imported incorrectly (e.g., named import instead of default), or the `PouchDB.plugin()` method was called before the PouchDB object was properly initialized.
  fix Ensure `import PouchDB from 'pouchdb';` is at the top of your file and that `PouchDB.plugin(PouchDBReplicator);` is called after PouchDB is ready.

• Error: Database not found or permission denied

  cause This error typically occurs during replication if the source or target database URL is incorrect, the database does not exist, or there are insufficient authentication credentials/permissions to access the remote database.
  fix Double-check the `source` and `target` URLs/names in your `_replicator` document. If replicating to a remote CouchDB, ensure `auth` options (username, password) are correctly provided in the replication document, or the user has appropriate roles set up.

• Error: Document update conflict

  cause When updating a replication document in the `_replicator` database, you must provide the correct `_rev` of the existing document. If the `_rev` is missing or stale, a conflict will occur.
  fix Before updating a replication document, fetch its current `_rev` (e.g., via `replicatorDb.get(id)`), then include that `_rev` in your `put()` or `post()` call. Alternatively, use a PouchDB upsert plugin if available.

• TypeError: Cannot read properties of undefined (reading 'name') on 'source' or 'target'

  cause If `source` or `target` are PouchDB database objects instead of names/URLs, this error suggests that the PouchDB instance itself (e.g., `localDb` in the quickstart) was not properly initialized or is `undefined` when its `.name` property is accessed.
  fix Ensure that `new PouchDB('db_name')` calls are awaited or handled as promises, and that the resulting PouchDB objects are valid before being used in the replication document.

Warnings

• breaking Version 4.0.0 was the first release built from a complete monorepo, changing internal structures and dependencies. It also addressed a security issue. While the impact on direct API usage for `pouchdb-replicator` itself might be minimal, users upgrading from pre-4.0.0 versions should be aware of potential broader ecosystem changes within `pouchdb-server`.
  Fix: Review the full `pouchdb-server` 4.0.0 changelog for details on monorepo migration and dependency impacts. Ensure all related PouchDB packages are compatible with this new structure.
• breaking Version 2.0.0 introduced breaking changes that correspond to `express-pouchdb` 2.0.0, specifically impacting database name encoding for adapters that store files. If database names contained '/' characters, existing databases might not be found. Additionally, version 2.0.0 onward uses prefixed replication fields (`_replication_state` instead of `replication_state`).
  Fix: For affected database names, migration may involve renaming database files or adjusting how names are handled. Ensure PouchDB is updated to a version where issue 2442 is solved to support the prefixed replication fields.
• gotcha A potential `EventEmitter` memory leak issue was fixed in version 4.1.0 (#233). Applications with many active replications or frequent replication job changes might have experienced memory consumption growth over time in earlier versions.
  Fix: Upgrade to `pouchdb-replicator@4.1.0` or later to benefit from the memory leak fix.
• gotcha Version 4.2.0 fixed an issue where `.info` errors were being swallowed, leading to silent failures or missed diagnostic information during replication.
  Fix: Upgrade to `pouchdb-replicator@4.2.0` or later to ensure proper error reporting for `.info` calls.
• breaking PouchDB (and by extension its plugins like `pouchdb-replicator`) has evolved towards ESM. While older versions might support CommonJS, modern PouchDB usage (especially with recent versions like v7+) strongly encourages ESM for better compatibility and tree-shaking.
  Fix: Adopt ES Module syntax (`import ... from '...'`) throughout your project. If bundling for older environments, ensure your build setup correctly transpiles ESM to CJS.
• deprecated The broader PouchDB ecosystem has seen significant shifts, with some perspectives considering PouchDB legacy for high-performance use cases due to revision handling overhead and bundle size. While `pouchdb-replicator` remains functional, consider the long-term architectural implications if performance or strict modern database standards are critical.
  Fix: For new projects with extreme performance requirements or specific modern sync patterns (e.g., WebRTC, GraphQL), evaluate alternative RxDB storage engines. For existing PouchDB applications, continue using `pouchdb-replicator` but be mindful of its inherent characteristics.

Install

• npm install pouchdb-replicator npm
• yarn add pouchdb-replicator yarn
• pnpm add pouchdb-replicator pnpm

Imports

• PouchDBReplicator
  wrong:

  const PouchDB = require('pouchdb');
  const PouchDBReplicator = require('pouchdb-replicator'); // CommonJS for older Node

  correct:

  import PouchDB from 'pouchdb';
  import PouchDBReplicator from 'pouchdb-replicator';

  The primary way to use this plugin is to import its default export and register it with `PouchDB.plugin()`. Ensure `pouchdb` itself is imported correctly first. While CommonJS is shown as 'wrong' for modern contexts, it's still prevalent in older Node.js projects, but ESM is preferred for PouchDB since v7.
• PouchDB.plugin
  wrong:

  new PouchDBReplicator();
  // or just importing without registering

  correct:

  PouchDB.plugin(PouchDBReplicator);

  PouchDB plugins must be registered with the global `PouchDB` object using the `.plugin()` method for their functionality to become available on database instances.
• PouchDB
  wrong:

  import { PouchDB } from 'pouchdb';
  // or not importing it at all

  correct:

  import PouchDB from 'pouchdb';

  `PouchDB` is typically imported as a default export, even though it exposes many named utilities. Forgetting to import it, or importing it incorrectly, will prevent plugin registration.

Quickstart

This quickstart demonstrates how to register `pouchdb-replicator` as a plugin and then initiate a continuous replication job by creating a document in the special `_replicator` database. This simulates CouchDB's declarative replication management.

import PouchDB from 'pouchdb';
import PouchDBReplicator from 'pouchdb-replicator';

// Register the PouchDB Replicator plugin
PouchDB.plugin(PouchDBReplicator);

async function setupPersistentReplication() {
  // Initialize a local PouchDB database
  const localDb = new PouchDB('my_local_db');

  // Define a remote PouchDB/CouchDB instance URL
  const remoteDbUrl = 'http://localhost:5984/my_remote_db'; // Ensure CouchDB is running or this is a valid PouchDB instance

  // The special _replicator database to manage replication jobs
  const replicatorDb = new PouchDB('_replicator');

  try {
    // Create a continuous replication job by posting a document to _replicator
    // This will instruct PouchDB-Replicator to start and manage the replication.
    const replicationJob = {
      _id: 'my-first-continuous-sync',
      source: localDb.name,        // Source database: 'my_local_db'
      target: remoteDbUrl,       // Target database: 'http://localhost:5984/my_remote_db'
      continuous: true,          // Keep replication running continuously
      live: true,                // Also track future changes (often implied by continuous)
      retry: true,               // Automatically retry on failure
      // For authenticated replication to a remote CouchDB:
      // auth: {
      //   username: process.env.COUCHDB_USERNAME ?? 'admin',
      //   password: process.env.COUCHDB_PASSWORD ?? 'password'
      // }
    };

    const response = await replicatorDb.put(replicationJob);
    console.log('Replication job started successfully:', response);

    // To stop or update the replication, you would modify or delete this document from _replicator
    // e.g., await replicatorDb.remove(response.id, response.rev);

  } catch (error: any) {
    console.error('Failed to set up replication job:', error);
    // Handle common errors like network issues, authentication failures, etc.
  }
}

setupPersistentReplication();