CouchDB component

The couchdb component saves, reads and deletes JSON documents in Apache CouchDB and consumes the database's changes feed.

Scheme: couchdb: · Crate: cameleer-datastores · Cargo feature: datastores · Consumer: yes · Producer: yes · Apache Camel: CouchDB

When to use it

• Store JSON documents over CouchDB's HTTP API, including from edge sites that later replicate to a central CouchDB.
• React to every change in a database: the consumer follows the _changes feed and routes each new, updated or deleted document.
• Save batches of documents in one _bulk_docs request.

URI format

couchdb:http://host[:port]/database[?options]
couchdb:https://host[:port]/database[?options]

The port defaults to 5984. https uses TLS with the system trust store, the global camel.ssl.* parameters or sslContextParameters=#bean.

Producer. Without a CouchDbMethod header the body (a map or JSON text) is saved: PUT /db/{_id} when it has an _id, else POST /db. A body with _rev updates that revision. CouchDbMethod=GET reads the document CouchDbId (or the id in the body); CouchDbMethod=DELETE deletes the document given by the body's _id and _rev or by the CouchDbId and CouchDbRev headers. A list body is saved with one _bulk_docs request.

Consumer. Follows _changes?feed=longpoll&include_docs=true from the current update sequence (or since). The body is the document.

Example

POST /notes saves the JSON body as a new document and answers with its id. createDatabase creates the database on first use.

- route:
    id: save-note
    from:
      uri: "platform-http:/notes?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - to: "couchdb:{{env:COUCHDB_URL:http://localhost:5984}}/notes?createDatabase=true&username={{env:COUCHDB_USER:admin}}&password={{env:COUCHDB_PASSWORD:secret}}"
        - setBody:
            simple: "${header.CouchDbId}"

This route follows the changes feed of the same database and logs every change.

- route:
    id: note-changes
    from:
      uri: "couchdb:{{env:COUCHDB_URL:http://localhost:5984}}/notes?username={{env:COUCHDB_USER:admin}}&password={{env:COUCHDB_PASSWORD:secret}}"
      steps:
        - log: "${header.CouchDbMethod} ${header.CouchDbId} rev ${header.CouchDbRev}"
        - to: "log:changes"

Rust DSL

ctx.add_routes(|b| {
    b.from("direct:save")
        .to("couchdb:http://localhost:5984/notes?createDatabase=true&username=admin&password=secret");
    b.from("direct:get")
        .set_header("CouchDbMethod", constant("GET"))
        .to("couchdb:http://localhost:5984/notes?username=admin&password=secret");
})?;

Options

Message headers

Errors: a revision conflict raises DocumentConflictException, a missing document NoDocumentException.

Run it with Docker

docker run --rm -p 8080:8080 \
  -e COUCHDB_URL=http://couchdb.example.com:5984 -e COUCHDB_USER=app -e COUCHDB_PASSWORD \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/notes.camel.yaml

Common questions

How do I update a document?

Send the document with its _id and current _rev. A stale _rev raises DocumentConflictException; read the latest revision with CouchDbMethod=GET and retry.

How do I resume the changes feed after a restart?

Store the last CouchDbSeq you processed and start the consumer with since=<seq>. Without since, the feed starts at the current sequence and skips older changes.

Is Couchbase supported?

No. Couchbase uses a binary key-value protocol that Cameleer does not implement.

Related

• mongodb: another document database.
• Apache Camel CouchDB component

Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building with it, please help fix it, whether you are a person or a coding agent: open an issue that describes what you saw, then fork the repository, fix it, add or update a test, run cargo test --workspace, and open a pull request. CONTRIBUTING.md explains the ground rules.