CouchDB

The CouchDB source copies a database with _all_docs and follows its _changes feed. It works with Apache CouchDB, IBM Cloudant and other servers that speak the CouchDB replication protocol.

Prerequisites

Nothing to enable on the server: the _changes feed is always available. The user needs read access to the database: an admin, or a member (reader) listed in the database's _security object:

curl -X PUT http://admin:secret@couch.internal:5984/_users/org.couchdb.user:cdc \
  -H 'Content-Type: application/json' \
  -d '{"name":"cdc","password":"change-me","roles":[],"type":"user"}'

curl -X PUT http://admin:secret@couch.internal:5984/products/_security \
  -H 'Content-Type: application/json' \
  -d '{"admins":{"names":[],"roles":[]},"members":{"names":["cdc"],"roles":[]}}'

Note that setting _security replaces the whole object; merge it with existing members.

Connection string

The server URL with optional basic-auth credentials. The database name goes in the task, not in the URL:

http://cdc:change-me@couch.internal:5984
https://cdc:change-me@account.cloudant.com

Task fields

Field	Meaning
`table`	The CouchDB database to follow (the source uses `database` when `table` is empty).

How changes are applied

Primary key. The document _id. CouchDB ids may contain characters Meilisearch does not allow in ids; they are escaped (see document ids).
Schema. Inferred from a sample of 100 documents.
Design documents (_design/…) are skipped everywhere. Attachment stubs (_attachments) are removed from documents; _rev is kept.
Snapshot. _all_docs with include_docs=true, 1,000 documents per page.
Changes are read with feed=longpoll (requests wait up to 30 seconds for changes), 1,000 changes per request. A change with "deleted": true deletes the document; other changes upsert the winning revision.
Transient HTTP failures are retried inside the source up to 5 times in a row before the task's own retry takes over.
CouchDB has no truncate. Deleting the database stops the task with a permanent error.

Positions and resume

Positions are the feed's opaque update sequences, kept verbatim (12-g1AAAA… on CouchDB 2 and later, 12 on 1.x). Resuming from one continues with the following changes; CouchDB may replay a few, which is harmless. If the server rejects a stored sequence, the position is lost and the task resyncs.

Troubleshooting

Error	Fix
`couchdb: authentication failed …; check the user and password in the dsn`	Fix the credentials in the URL.
`couchdb: the user may not read database "products" …; add it to the database _security members`	Add the user to the database's `_security` members.
`couchdb: database "products" not found …`	Create the database or fix the task's `table`.
`couchdb: invalid dsn …: want http(s)://user:password@host:5984`	Use an absolute `http` or `https` URL.