🎯

couchdb

🎯Skill
g1joshi/agent-skills1 Installs9Last Updated Feb 10, 2026

Installation

$npx skills add g1joshi/agent-skills --skill couchdb

Run 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.

Run it (Claude Code)/couchdb
Install 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/couchdb/
  • All projects ~/.claude/skills/couchdb/

These paths are for Claude Code. For other tools, the command above puts it in the right place.

Expert Apache CouchDB assistance covering HTTP REST APIs, Mango queries, conflict resolution, and offline-first mobile sync. Use when building multi-master replicated apps or PouchDB browser synchronization.

Apache CouchDB

CouchDB is a database that completely embraces the web. It speaks JSON and HTTP. It is unique for its multi-master replication protocol, making it ideal for "Offline First" apps.

When to Use

  • Offline-First Synchronized Web & Mobile Apps: Pairing with PouchDB in web browsers to enable full offline operation with automated background sync.
  • RESTful HTTP Document Storage: Accessing and mutating JSON documents purely through standard HTTP verbs without proprietary drivers.
  • Append-Only Document Versioning: Tracking document revision histories and managing conflicting edits explicitly.
  • Distributed Peer-to-Peer Replication: Replicating databases bidirectionally across edge servers, embedded devices, and cloud nodes.

Quick Start

# Create a document via REST API
curl -X PUT http://admin:password@127.0.0.1:5984/my_database/doc1 \
     -d '{"key": "value"}'

Core Concepts

Pure HTTP/RESTful Interface

Every database operation maps directly to standard HTTP methods:

# 1. Create a document
curl -X POST http://admin:password@127.0.0.1:5984/mydb \
  -H "Content-Type: application/json" \
  -d '{"title": "Offline-First Architectures", "status": "published"}'
# Returns: {"ok": true, "id": "8f3d1e1c...", "rev": "1-a1b2c3d4..."}

# 2. Retrieve document by ID
curl -X GET http://admin:password@127.0.0.1:5984/mydb/8f3d1e1c...

Multiversion Concurrency Control (MVCC) & Revisions (_rev)

Updating documents requires passing the active revision tag to prevent accidental overwrites:

# Update requires passing latest _rev token
curl -X PUT http://admin:password@127.0.0.1:5984/mydb/8f3d1e1c... \
  -H "Content-Type: application/json" \
  -d '{"_rev": "1-a1b2c3d4...", "title": "Updated Title", "status": "draft"}'

Bi-Directional Master-Master Replication

Syncs databases seamlessly between independent nodes:

// POST to /_replicate
{
  "source": "http://edge-node.local:5984/pos_sales",
  "target": "https://admin:pass@cloud.corp.com:5984/pos_sales",
  "continuous": true,
  "create_target": true
}

Common Patterns

Conflict-Aware Document Updating

Problem: Concurrent offline writes in CouchDB create document revision forks (_conflicts).

Solution: Fetch existing revision and resolve conflicts deterministically:

# 1. Fetch current revision
REV=$(curl -s "http://127.0.0.1:5984/mydb/doc1" | jq -r '._rev')

# 2. Update with required _rev header
curl -X PUT "http://127.0.0.1:5984/mydb/doc1"   -H "Content-Type: application/json"   -d "{"_rev": "$REV", "title": "Updated Document", "status": "resolved"}"

Best Practices

Do:

  • Pair with PouchDB in Browsers: Use PouchDB locally in client IndexedDB; sync automatically with CouchDB on network recovery.
  • Run Regular Database Compaction: Execute POST /mydb/_compact to clean up old MVCC revision trees and reclaim disk space.
  • Design Conflict Resolution Explicitly: Handle deterministic conflict resolution in application code when concurrent offline edits occur.
  • Create Mango Indexes: Define JSON indexes (_index) to optimize ad-hoc JSON querying via _find.

Don't:

  • Rely on CouchDB for high-throughput OLTP transactions: CouchDB is built for offline sync and eventual consistency, not rapid transactions.
  • Ignore the _rev parameter: Forgetting to handle 409 Conflict responses causes user updates to drop.
  • Expose raw CouchDB admin ports to public networks: Protect port 5984 behind Nginx or Cloudflare reverse proxies.

Troubleshooting

ErrorCauseSolution
{"error":"conflict","reason":"Document update conflict."}Stale _rev submitted during document PUT operation.Fetch latest document version and reapply changes with current _rev.
Database size growing excessivelyOld revision history retained by MVCC storage engine.Run database and view compaction: POST /mydb/_compact.
Unauthorized (401)Server running in non-admin party mode without auth credentials.Provide Basic Auth header or create session cookie via POST /_session.

References

More from this repository10