CouchDB - filtered replication by example - Morris Jobke

I just want to document what is needed to get a filtered replication between two databases inside CouchDB 2.2.0 up and running. I spend quite some time figuring it out and couldn’t find any useful resource that sums it up.

I used capital cased names where specific names need to be placed - if there is the same placeholder it needs to be the same name.

The goal is to replicate SOURCE_DATABASE to TARGET_DATABASE while applying a filter function that is named DESIGNDOCUMENT/NAME. The filter function in the example checks if the attribute _id starts with abc.

First we create a document that describes the filter. This document is a design document and needs to be placed in the source database under /SOURCE_DATABASE/_design/DESIGNDOCUMENT:

{
  "_id": "_design/DESIGNDOCUMENT",
  "filters": {
    "NAME": "function(doc, req) { if (doc._id.substr(0, 3) === 'abc') { return true; } return false; }"
  }
}

To actually test the filter I used a query against the /_changes endpoint of the database:

$ curl "http://DOMAIN:5984/SOURCE_DATABASE/_changes?filter=DESIGNDOCUMENT%2FNAME&feed=normal&style=all_docs&since=0&timeout=10000"

This shows the output and potential errors in the JavaScript code of the filter.

For the actual replication you need to create following documents in the _replicator database for the one time replication of existing documents:

{
  "_id": "ID",
  "source": "http://DOMAIN:5984/SOURCE_DATABASE",
  "target": "http://DOMAIN:5984/TARGET_DATABASE",
  "filter": "DESIGNDOCUMENT/NAME"
}

And I created a continuous replication document as well:

{
  "_id": "ID-continuous",
  "source": "http://DOMAIN:5984/SOURCE_DATABASE",
  "target": "http://DOMAIN:5984/TARGET_DATABASE",
  "filter": "DESIGNDOCUMENT/NAME",
  "continuous": true
}

Following documentation pages helped me to understand how the replication works in general:

Quite interesting in this regard could also be the blog post “Filtered replication: from Couch to Pouch and back at the PouchDB blog.