couchbase-eventing

Couchbase Eventing

A skill for designing and operating Couchbase Eventing functions — JavaScript that runs in response to document mutations in a source collection.

Distinct from:

• couchbase-mcp — calling admin_eventing_* tools to deploy and manage functions
• couchbase-app-integration — SDK-based DCP consumer code for change processing outside the cluster
• couchbase-data-modeling — document shape decisions

If the conversation is "I want to run code when a document changes," this is the right skill.

When this skill applies

• "How do Eventing functions work?"
• "How do I deploy an Eventing function?"
• "How do I write an OnUpdate handler?"
• "How do I call an external API from Eventing?"
• "Can I run SQL++ from inside an Eventing function?"
• "How do I sync data between two collections automatically?"
• "Eventing function is deployed but nothing happens"
• "How do I debug an Eventing function?"
• "What's the metadata bucket / keyspace for?"
• "How do I handle errors in Eventing functions?"

Pick the right reference

Question	Read
"How do I write the JavaScript? OnUpdate, OnDelete, cron, curl, N1QL?"	references/function-authoring.md
"How do I configure and deploy a function — source, metadata, workers, bindings?"	references/deployment.md
"Function isn't triggering / processing slowly / throwing errors — what's wrong?"	references/troubleshooting.md

Three core principles

Principle 1 — Eventing is exactly-once delivery from the DCP feed, not exactly-once execution. The Eventing service reads from Couchbase's internal DCP (Database Change Protocol) feed. Each mutation triggers OnUpdate or OnDelete once in the steady state. But during node failures, rebalances, or function redeploys, a mutation can be delivered more than once. Write your handlers to be idempotent — running the same function against the same document twice should produce the same result.

Principle 2 — The metadata keyspace is reserved; never store application data there. The Eventing service uses the metadata keyspace internally to track which mutations have been processed (checkpointing), manage timers, and store function state. Writing application documents into it causes unpredictable behaviour. Create a dedicated bucket/scope/collection for metadata, separate from your application data.