Couchbase Introduction

What is Couchbase?

Couchbase is an enterprise NoSQL database that combines document storage, key-value caching, full-text search, analytics, and eventing in a single platform. It was formed from the merger of CouchDB and Membase (a Memcached-based caching system) in 2011.

The result is a database that brings together two worlds: the flexibility of JSON document storage and the performance of an in-memory cache. Every document in Couchbase is stored in memory as well as on disk, giving sub-millisecond key-value access alongside rich query capabilities.

Couchbase's Architecture

Buckets, Scopes, and Collections

Couchbase organizes data hierarchically:

• Cluster — A set of nodes working together
• Bucket — A named container for data (like a database). Configures memory quota, persistence, and replication.
• Scope — A namespace within a bucket (like a schema)
• Collection — A group of documents within a scope (like a table)

Cluster
  └── Bucket: myapp
        ├── Scope: _default
        │     └── Collection: _default
        └── Scope: ecommerce
              ├── Collection: users
              ├── Collection: orders
              └── Collection: products

Memory-First Architecture

Couchbase stores all active data in memory (bounded by the configured memory quota) and persists to disk asynchronously. This provides:

• Sub-millisecond key-value operations — Get/Set by document key in < 1ms
• No cold cache issues — Data is warm on startup
• High throughput — In-memory operations without disk I/O bottlenecks

N1QL: SQL for JSON

Couchbase's query language is N1QL (Non-First Normal Form Query Language, pronounced "nickel") — a SQL dialect for querying JSON documents. If you know SQL, you can query Couchbase immediately.

-- Standard SQL-like syntax on JSON documents
SELECT u.name, u.email, COUNT(o.id) AS order_count
FROM ecommerce.users u
JOIN ecommerce.orders o ON META(o).id LIKE 'order:' || META(u).id || '%'
WHERE u.tier = 'premium'
GROUP BY u.name, u.email
HAVING COUNT(o.id) > 5
ORDER BY order_count DESC
LIMIT 20;

This is a significant differentiator from MongoDB (which uses its own aggregation pipeline) or DynamoDB (which has very limited query capabilities). Developers familiar with SQL have almost no learning curve for basic queries.

Setting Up Couchbase

Docker (Community Edition):

docker run -d --name couchbase \
  -p 8091-8097:8091-8097 \
  -p 11210:11210 \
  couchbase:community

# Open the web console
open http://localhost:8091

Follow the setup wizard to create a cluster. Set the Admin username and password, configure memory quotas, and create your first bucket.

Install the SDK:

npm install couchbase

import couchbase from 'couchbase';

const cluster = await couchbase.connect('couchbase://localhost', {
  username: 'Administrator',
  password: 'password',
});

const bucket = cluster.bucket('myapp');
const collection = bucket.defaultCollection();

// Key-value: ultra-fast
await collection.upsert('user:alice', {
  name: 'Alice',
  email: 'alice@example.com',
  tier: 'premium',
});

const result = await collection.get('user:alice');
console.log(result.content);