couchbase-app-integration

Couchbase application integration

A skill for building application code that talks to Couchbase. Distinct from the three sibling skills:

• couchbase-data-modeling — what to store (server-side)
• couchbase-sizing — how much capacity (resource planning)
• couchbase-mcp — operations on an existing cluster (admin)
• couchbase-app-integration (this skill) — how application code reads, writes, and handles errors against Couchbase

If the conversation is "I'm writing Python (or Java, Node, etc.) code that talks to Couchbase," this is the right skill.

When this skill applies

• "Which Couchbase SDK should I use?"
• "How do I set up the connection?"
• "What's the right way to handle retries?"
• "Should I use synchronous or asynchronous?"
• "What durability level for this write?"
• "Bulk inserting a million documents — how?"
• "Transactions in [language]?"
• "Active-active XDCR — how does my code handle conflicts?"
• "Why does my client get [error]?"

Pick the right reference

Question	Read
"Which SDK / which version / install how?"	references/sdks.md
"How do I connect — strings, TLS, mTLS, pooling, lifecycle?"	references/connection-management.md
"Retries, timeouts, circuit breakers, transient vs durable errors?"	references/error-handling.md
"Durability levels and scan consistency — what to pick?"	references/durability-and-consistency.md
"Bulk ops, async patterns, batching — making it fast?"	references/performance-patterns.md
"Multi-document transactions in code — when, how, gotchas?"	references/transactions-app-side.md
"Active-active XDCR conflicts — what does my app need to do?"	references/xdcr-app-aware.md

The four design questions for every Couchbase app

Before writing any client code, the answers to these four questions determine 80% of what the integration looks like:

1. Sync or async? Latency-sensitive request/response servers usually want async. Batch and ETL code can use sync. Mixing is fine but pick per-component.
2. What durability is required? From "best-effort" (lowest latency, no guarantees on power loss) up to "persist to majority" (slowest, durable through cluster-wide power loss). Most workloads want Majority — see durability-and-consistency.md.
3. What's the consistency for reads? Index-backed queries default to NotBounded (eventually consistent) which is fast but may miss recent writes. For read-your-own-writes patterns, use RequestPlus. See same reference.
4. How does the code handle failure? Cluster failovers, network blips, individual node restarts — the SDKs auto-handle most of this, but your retry/timeout policy determines whether outages are seamless or visible. See error-handling.md.