couchbase
π―SkillInstallation
npx skills add g1joshi/agent-skills --skill couchbaseRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/couchbaseInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/couchbase/ - All projects
~/.claude/skills/couchbase/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub βExpert Couchbase NoSQL assistance covering N1QL/SQL++ queries, memory-first caching, document scopes, and cross-datacenter replication (XDCR). Use when building ultra-low latency JSON document platforms.
Couchbase
Couchbase works as a Key-Value store (managed memory cache) + Document Database. It is famous for its "memory-first" architecture and N1QL (SQL for JSON).
When to Use
- Memory-First NoSQL Document Store: Applications requiring sub-millisecond document lookups powered by an integrated managed memory cache.
- SQL for JSON (N1QL / SQL++): Querying JSON documents using familiar SQL syntax with joins, nested arrays, and subqueries.
- Distributed Key-Value + Full-Text Search: Unifying key-value caching, document storage, and vector/full-text search in a single cluster.
- Mobile Edge Data Sync (Couchbase Lite): Synchronizing embedded mobile database instances with cloud clusters using Sync Gateway.
Quick Start
-- N1QL Query
SELECT u.name, ARRAY_AGG(o.item) as orders
FROM `travel-sample`.inventory.users u
JOIN `travel-sample`.inventory.orders o ON u.id = o.user_id
WHERE u.city = "Paris"
GROUP BY u.name;
Core Concepts
Memory-First VBucket Architecture
Documents are mapped across 1024 virtual buckets (vBuckets), cached directly in RAM before being asynchronously written to disk:
[ Application Client ] ββSub-Millisecond Read/Writeβββ [ Managed Memory Cache (RAM) ]
β (Async Flush)
βΌ
[ Append-Only Disk Storage ]
SQL++ (N1QL) Declarative JSON Queries
Executes full SQL expressions over schemaless JSON structures:
-- Query nested JSON orders in Couchbase SQL++
SELECT
meta().id AS orderId,
customer.email,
ARRAY_SUM(items[*].price) AS totalAmount
FROM `commerce`.`orders` AS o
WHERE status = 'PAID'
AND ANY item IN items SATISFIES item.category = 'Electronics' END
ORDER BY totalAmount DESC
LIMIT 20;
Scopes and Collections Multi-Tenancy
Organizes documents into logical namespaces mimicking relational databases:
[ Bucket: enterprise ]
βββ [ Scope: billing ]
β βββ [ Collection: invoices ]
β βββ [ Collection: payments ]
βββ [ Scope: catalog ]
βββ [ Collection: products ]
Common Patterns
SQL++ (N1QL) Secondary Indexing and Querying
Problem: Ad-hoc JSON document filtering results in slow primary index table scans.
Solution: Build covering secondary GSI indexes for high-throughput queries:
CREATE INDEX idx_orders_status ON `ecommerce`.`sales`.`orders` (customerId, orderStatus, orderDate)
WHERE orderStatus != 'cancelled';
SELECT customerId, orderDate, total
FROM `ecommerce`.`sales`.`orders`
WHERE customerId = "cust_987" AND orderStatus = "completed"
ORDER BY orderDate DESC;
Best Practices
Do:
- Use Sub-Document API for Partial Mutations: Mutate specific JSON array items or attributes without fetching/resaving the entire document.
- Create Global Secondary Indexes (GSI) Covering Queries: Index the exact fields in
WHEREandSELECTto enable index-only scans. - Leverage Key-Value Operations for Hot Lookups: Use
get()andupsert()key-value APIs for sub-millisecond reads rather than N1QL queries. - Size Bucket RAM Quotas Carefully: Allocate sufficient RAM to ensure high active working set cache-hit ratios.
Don't:
- Use Primary Indexes in Production: Avoid
CREATE PRIMARY INDEX; primary scans scan all documents in the collection. - Store massive binary blobs in documents: Keep documents under 1MB; store images and media in object storage.
- Ignore Cross-Datacenter Replication (XDCR) lag: Monitor XDCR replication queues when synchronizing across multi-region clusters.
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
No index available for query | Missing secondary index matching the WHERE predicate in SQL++ query. | Create an index covering query filter and projection columns. |
Temporary failure / Out of memory | Couchbase bucket memory quota exhausted by high item count. | Increase bucket RAM quota or configure eviction policy (value-only vs full eviction). |
DocumentExistsException | Key already exists in bucket during insert operation. | Use upsert instead of insert if overwrite semantics are intended. |
References
More from this repository10
A template skill providing a starter framework for creating new agent skills with structured sections for triggers, quick start examples, and capability descriptions.
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill