Registry / database / pouchdb-replicator

pouchdb-replicator

JSON →
library4.2.0jsnpmunverified

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.

npm install pouchdb-replicator
INSTALL
IMPORT
SIG · POUCHDB-REPLICATOR
P
pouchdb-replicator
databasejavascriptv4.2.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.

PouchDBReplicator
✓ import PouchDB from 'pouchdb'; import PouchDBReplicator from 'pouchdb-replicator';
✗ const PouchDB = require('pouchdb'); const PouchDBReplicator = require('pouchdb-replicator'); // CommonJS for older Node
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
✓ PouchDB.plugin(PouchDBReplicator);
✗ new PouchDBReplicator(); // or just importing without registering
PouchDB plugins must be registered with the global `PouchDB` object using the `.plugin()` method for their functionality to become available on database instances.
PouchDB
✓ import PouchDB from 'pouchdb';
✗ import { PouchDB } from 'pouchdb'; // or not importing it at all
`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.

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();
Debug
Known issues
breakingVersion 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.
affects: >=4.0.0 <4.0.1
breakingVersion 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.
affects: >=2.0.0 <3.0.0
gotchaA 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.
affects: >=2.0.0 <4.1.0
gotchaVersion 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.
affects: >=4.0.0 <4.2.0
breakingPouchDB (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.
affects: >=7.0.0 (PouchDB)
deprecatedThe 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.
affects: >=4.0.0
Errors
Common errors & fixes
TypeError: PouchDB.plugin is not a function
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
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
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'
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.
Upgrade
Version history
4.2.0latest on npm
Audit
Dependencies
pouchdbrequiredThis package is a PouchDB plugin and extends the core PouchDB object.
Agent activity
7 hits · last 30 days
node
6
Resources
pouchdb-replicator — npm install pouchdb-replicator · libregistry