How to Replicate Data in CouchDB: Step-by-Step Guide

Replication in CouchDB is a critical feature that allows data synchronization across multiple servers or databases, supporting distributed architectures and ensuring higher availability. This tutorial walks you through the essential steps to set up and manage data replication in CouchDB. Whether you aim to replicate locally or between remote nodes, this guide is for you.

Prerequisites

Installed CouchDB server(s). You can follow our How to Install CouchDB: Complete Step-by-Step Guide for installation instructions.
Basic knowledge of CouchDB and HTTP API.
Access to CouchDB’s Fauxton interface or curl/bash tools.
Network connectivity between CouchDB instances (for remote replication).

Understanding CouchDB Replication

CouchDB uses an incremental replication model. Only changes since the last sync are transferred. Replication can be one-shot (manual, one-time sync) or continuous (automatic ongoing sync). It works over HTTP/HTTPS and supports filtered replication if needed.

Types of Replication

Push Replication: Source database pushes changes to the target.
Pull Replication: Target database pulls changes from the source.

Step 1: Verify CouchDB Endpoints

Make sure the source and target CouchDB instances are reachable. You can check by visiting http://source-host:5984/ and http://target-host:5984/ in a browser or via curl.

Step 2: Setup Basic Replication Using Fauxton

Open CouchDB Fauxton UI (usually http://localhost:5984/_utils/).
Navigate to the Replication section.
Fill in the “source” and “target” fields with your database names or URLs, e.g., http://source-host:5984/mydatabase.
Choose Continuous if you want ongoing replication or leave it unchecked for one-shot.
Click “Replicate” to start replication.

Step 3: Setup Replication Using the REST API

You can also create a replication document via API.

curl -X POST http://localhost:5984/_replicate \
-H 'Content-Type: application/json' \
-d '{
  "source": "http://source-host:5984/mydatabase",
  "target": "http://target-host:5984/mydatabase",
  "continuous": true
}'

Note

If authentication is required, include credentials in the URL, e.g., http://user:password@source-host:5984/dbname.

Step 4: Use Replication Documents for Job Persistence

Unlike one-shot replication, continuous replications run indefinitely. CouchDB stores these replication jobs as documents in its _replicator database. You can manage and monitor these jobs from there.

Step 5: Replication Filtering and Options

To replicate only a subset of documents, use filters defined as functions in design documents.

curl -X POST http://localhost:5984/_replicate \
-H 'Content-Type: application/json' \
-d '{
  "source": "http://source-host:5984/mydatabase",
  "target": "http://target-host:5984/filtered_db",
  "filter": "design_doc/filter_func",
  "query_params": {"type": "important"}
}'

Troubleshooting Common Issues

Replication stops working: Check CouchDB logs to identify errors.
Often network issues or auth failures cause problems.
Conflicts: In multi-master setups, document conflicts can appear. Use CouchDB’s conflict resolution strategies.
Performance problems: For large databases, consider replication filters or chunking data into smaller sets.
Authentication: Verify credentials and permissions are correct on both ends.