Skip to content

cloudthinker-ai/CloudSkills / skills/connections/analyzing-couchbase

analyzing-couchbase

Unverified

Use when working with Couchbase — couchbase bucket analysis, index advisor, N1QL query performance, XDCR status, and cluster health monitoring.

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

ShortcutCounterWhy
"I'll skip discovery and check known resources"Always run Phase 1 discovery firstResource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"Follow the full discovery → analysis flowQuick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"Audit configuration explicitlyDefaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"Always check relevant metrics when availableAPI/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 errorAssumed 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
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall