{"library":"pouchdb-replicator","title":"PouchDB Replicator Plugin","description":"pouchdb-replicator is a PouchDB plugin that simulates the functionality of CouchDB's `_replicator` database daemon. Instead of initiating one-off or programmatic replication calls (e.g., `db.replicate()`), this plugin allows developers to define and manage persistent replication jobs declaratively by simply writing documents to a special `_replicator` database. This enables scenarios like continuous synchronization across application restarts and simplifies the management of complex replication topologies. The current stable version is 4.2.0, part of the pouchdb-server monorepo. It receives regular maintenance updates, focusing on bug fixes, dependency updates, and minor enhancements. Its key differentiator is providing a CouchDB-compatible declarative replication interface directly within PouchDB, making it ideal for applications requiring robust offline-first capabilities and seamless synchronization with CouchDB or other PouchDB instances.","language":"javascript","status":"active","last_verified":"Wed Apr 22","install":{"commands":["npm install pouchdb-replicator"],"cli":null},"imports":["import PouchDB from 'pouchdb';\nimport PouchDBReplicator from 'pouchdb-replicator';","PouchDB.plugin(PouchDBReplicator);","import PouchDB from 'pouchdb';"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import PouchDB from 'pouchdb';\nimport PouchDBReplicator from 'pouchdb-replicator';\n\n// Register the PouchDB Replicator plugin\nPouchDB.plugin(PouchDBReplicator);\n\nasync function setupPersistentReplication() {\n  // Initialize a local PouchDB database\n  const localDb = new PouchDB('my_local_db');\n\n  // Define a remote PouchDB/CouchDB instance URL\n  const remoteDbUrl = 'http://localhost:5984/my_remote_db'; // Ensure CouchDB is running or this is a valid PouchDB instance\n\n  // The special _replicator database to manage replication jobs\n  const replicatorDb = new PouchDB('_replicator');\n\n  try {\n    // Create a continuous replication job by posting a document to _replicator\n    // This will instruct PouchDB-Replicator to start and manage the replication.\n    const replicationJob = {\n      _id: 'my-first-continuous-sync',\n      source: localDb.name,        // Source database: 'my_local_db'\n      target: remoteDbUrl,       // Target database: 'http://localhost:5984/my_remote_db'\n      continuous: true,          // Keep replication running continuously\n      live: true,                // Also track future changes (often implied by continuous)\n      retry: true,               // Automatically retry on failure\n      // For authenticated replication to a remote CouchDB:\n      // auth: {\n      //   username: process.env.COUCHDB_USERNAME ?? 'admin',\n      //   password: process.env.COUCHDB_PASSWORD ?? 'password'\n      // }\n    };\n\n    const response = await replicatorDb.put(replicationJob);\n    console.log('Replication job started successfully:', response);\n\n    // To stop or update the replication, you would modify or delete this document from _replicator\n    // e.g., await replicatorDb.remove(response.id, response.rev);\n\n  } catch (error: any) {\n    console.error('Failed to set up replication job:', error);\n    // Handle common errors like network issues, authentication failures, etc.\n  }\n}\n\nsetupPersistentReplication();","lang":"typescript","description":"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.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}