Couchbase Analysis Skill

Analyze and optimize Couchbase clusters with safe, read-only operations.

MANDATORY: Two-Phase Execution

You MUST follow this two-phase pattern. Skipping Phase 1 causes hallucinated bucket/scope/collection names.

Phase 1: Discovery (ALWAYS run first)

#!/bin/bash

# 1. Cluster overview
couchbase-cli server-list -c "$CB_HOST" -u "$CB_USER" -p "$CB_PASSWORD"

# 2. List buckets
couchbase-cli bucket-list -c "$CB_HOST" -u "$CB_USER" -p "$CB_PASSWORD"

# 3. List scopes and collections
cbq -e "$CB_HOST" -u "$CB_USER" -p "$CB_PASSWORD" \
    --script="SELECT * FROM system:scopes WHERE \`bucket\` = 'my_bucket';"

# 4. Sample documents (never assume field names)
cbq -e "$CB_HOST" -u "$CB_USER" -p "$CB_PASSWORD" \
    --script="SELECT META().id, * FROM \`my_bucket\`.\`_default\`.\`_default\` LIMIT 5;"

# 5. List indexes
cbq -e "$CB_HOST" -u "$CB_USER" -p "$CB_PASSWORD" \
    --script="SELECT * FROM system:indexes WHERE keyspace_id = 'my_bucket';"

Phase 1 outputs:

• Cluster node list and services
• Buckets with memory/disk usage
• Scopes, collections, and sample documents

Phase 2: Analysis (only after Phase 1)

Only reference buckets, scopes, collections, and fields confirmed in Phase 1.

Shell Script Patterns

Helper Function

#!/bin/bash

# Core N1QL runner — always use this
cb_query() {
    local query="$1"
    cbq -e "${CB_HOST:-localhost}" -u "${CB_USER:-Administrator}" -p "${CB_PASSWORD}" \
        --script="$query" --quiet
}

# REST API helper
cb_api() {
    local endpoint="$1"
    curl -s -u "${CB_USER:-Administrator}:${CB_PASSWORD}" \
        "http://${CB_HOST:-localhost}:8091$endpoint"
}

Anti-Hallucination Rules

• NEVER reference a bucket without confirming via bucket-list or REST API
• NEVER reference field names without seeing them in sample documents
• NEVER assume scope/collection names — always check system:scopes
• NEVER assume index names — always query system:indexes
• NEVER guess node services — check cluster topology first

Safety Rules

• READ-ONLY ONLY: Use only SELECT, EXPLAIN, system catalog queries, REST GET endpoints
• FORBIDDEN: INSERT, UPSERT, DELETE, DROP, CREATE INDEX, bucket-edit without explicit user request
• ALWAYS add LIMIT to N1QL queries
• Use EXPLAIN before running expensive queries
• Use REST GET endpoints for cluster info — never POST/PUT/DELETE

Common Operations

Cluster Health Overview

#!/bin/bash
echo "=== Cluster Nodes ==="
cb_api "/pools/nodes" | jq '.nodes[] | {hostname, status, services, clusterMembership, memoryTotal: .memoryTotal, memoryFree: .memoryFree}'

echo ""
echo "=== Bucket Summary ==="
cb_api "/pools/default/buckets" | jq '.[] | {name, bucketType, ramQuota: (.quota.ram/1024/1024|round), ramUsed: (.basicStats.memUsed/1024/1024|round), diskUsed: (.basicStats.diskUsed/1024/1024|round), itemCount: .basicStats.itemCount}'

echo ""
echo "=== Cluster RAM Quota ==="
cb_api "/pools/default" | jq '{memoryQuota: .memoryQuota, indexMemoryQuota: .indexMemoryQuota, ftsMemoryQuota: .ftsMemoryQuota}'

N1QL Performance Analysis

#!/bin/bash
echo "=== Active Requests ==="
cb_query "SELECT * FROM system:active_requests ORDER BY elapsedTime DESC LIMIT 10;"

echo ""
echo "=== Completed Requests (slow) ==="
cb_query "SELECT statement, elapsedTime, resultCount, errorCount FROM system:completed_requests WHERE elapsedTime > '1s' ORDER BY elapsedTime DESC LIMIT 10;"

echo ""
echo "=== Index Advisor ==="
QUERY="SELECT * FROM \`my_bucket\` WHERE type = 'user' AND status = 'active'"
cb_query "ADVISE $QUERY;"

Index Analysis

#!/bin/bash
BUCKET="${1:-my_bucket}"

echo "=== Indexes on $BUCKET ==="
cb_query "SELECT name, state, using, index_key, condition, is_primary FROM system:indexes WHERE keyspace_id = '$BUCKET' ORDER BY name;"

echo ""
echo "=== Index Stats ==="
cb_api "/pools/default/buckets/$BUCKET/stats" | jq '.op.samples | {index_num_docs_queued: .index_num_docs_queued[-1], index_num_requests: .index_num_requests[-1], index_resident_percent: .index_resident_percent[-1]}'

XDCR Status

#!/bin/bash
echo "=== XDCR Remote Clusters ==="
cb_api "/pools/default/remoteClusters" | jq '.[] | {name, hostname, uuid, deleted}'

echo ""
echo "=== XDCR Replications ==="
cb_api "/pools/default/tasks" | jq '[.[] | select(.type == "xdcr") | {id, status, source, target, filterExpression, pauseRequested}]'

Output Format

Present results as a structured report:

Analyzing Couchbase Report
══════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Counter-Rationalizations

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative

Common Pitfalls

• Missing primary index: N1QL queries fail without at least a primary index or a covering secondary index
• USE KEYS vs scan: Use USE KEYS for direct document access — much faster than scanning
• Memory quota: Each bucket has a fixed RAM quota — exceeding it causes evictions
• XDCR conflict resolution: Default is revision-based — understand implications for bidirectional replication
• N1QL vs KV: Use KV (SDK Get) for single-document access, N1QL for multi-document queries
• Index replicas: Production should have index replicas — check with system:indexes