Why does a filtered CouchDB replication silently stop propagating deletions, and how do you fix the filter?

## How filtered replication works A filtered replication passes each row of the source's `_changes` feed through a predicate before deciding whether to replicate that document. The predicate is one of: - a JavaScript function stored under `filters` in a design document, referenced as `filter: "ddoc/name"`; - a Mango `selector` supplied on the replication; - `doc_ids`, a fixed list of document ids; - `_design`, matching only design documents. The filter runs **on the source**, per change. A JavaScript filter is executed by the external query server, which means every change in the database is serialised out to another process and back — a real cost on a busy database. A `selector` is evaluated natively and is much cheaper, which is the usual reason to prefer it when the predicate is expressible as a selector. ## What a deletion looks like This is the crux. When you delete a document with `DELETE /db/{id}?rev=...`, CouchDB does not remove it; it writes a new revision marked deleted. That new revision keeps essentially nothing of the old body. What the change feed hands your filter is: ```json {"_id": "order:912", "_rev": "5-3f21", "_deleted": true} ``` No `type`, no `ownerId`, no `tenant` — whatever your filter tests is simply absent. ## Why the replication goes quiet So a filter such as: ```javascript function (doc, req) { return doc.type === 'order'; } ``` returns `false` for the tombstone. The deletion is dropped, and the target retains the last version it saw. The source and the target now disagree permanently, and nothing reports an error: the replication is healthy, it is doing exactly what you told it to do. This is one of the most common CouchDB support questions and one of the easiest to miss in testing, because tests usually create and update documents and rarely delete them. The same reasoning applies to a selector filter that matches on a business field. It is not a quirk of the JavaScript path; it is a property of what a tombstone contains. ## Fix one: let deletions through ```javascript function (doc, req) { if (doc._deleted) { return true; } return doc.type === 'order'; } ``` This is the standard fix and it is correct, with one side effect worth knowing: the filter now passes deletions for documents that never matched the filter in the first place, so the target accumulates tombstones for documents it never held. That costs a little space in the revision tree until compaction, and it is almost always the right trade. ## Fix two: keep the discriminator on the tombstone Instead of `DELETE`, write the deletion as an ordinary update that sets `_deleted: true` while retaining the fields the filter needs: ```javascript db.put({ _id: doc._id, _rev: doc._rev, type: doc.type, _deleted: true }); ``` CouchDB honours `_deleted` on a write, and the fields you kept survive on the deleted revision, so the filter matches. This keeps the target free of irrelevant tombstones and it is the cleaner option when deletes are routine and the discriminator is stable. It requires every deletion path in the application to cooperate, which is the reason many teams take fix one instead. ## The other half of the trap: filters do not retract A filter decides what a replication **transfers**; it never removes anything from the target. If a document is replicated because `type === 'order'`, and later someone changes `type` to `"draft"`, the new revision no longer matches, so the update is not transferred — and the target keeps the old, now-stale copy indefinitely. The target is not "the set of documents matching the filter"; it is "everything that ever matched, in the state it was in when it last matched". If you need documents to leave the target when they stop matching, you must model that explicitly: delete the document (with a filter that passes deletions), or move it by deleting it from a per-scope database and creating it elsewhere. ## Cost and operational notes Because the filter's source code contributes to the replication's identity, editing a filter function invalidates the recorded checkpoint and the replication restarts from the beginning of the change feed. Deploying the `_deleted` guard to a large existing replication therefore triggers a full re-scan — it will not re-transfer documents the target already has, but it will take time and I/O, so schedule it. Finally, remember that a filter is not an access-control mechanism. It shapes a transfer, not a permission; a client that can read the source database can read everything in it regardless of what any replication filter says.