Couchbase Developer cheat sheet

Document keys are unique per bucket and immutable; choose keys that distribute writes evenly (e.g., type::id::counter) to avoid hot partitions.

Embed when child data is read with the parent and bounded in size; reference when data is large, shared, or updated independently - Couchbase has no joins, only N1QL JOINs across documents.

N1QL SELECT uses keyspace bucket.scope.collection; USE KEYS avoids index scans when the document key is known.

CREATE INDEX is asynchronous; poll system:indexes for state 'online' before relying on it, and use covering indexes (INCLUDE) to avoid fetch.

Query consistency: request_plus waits for index updates from the request time; use it only when read-after-write is required because it adds latency.

Array operations: ARRAY_FOR, ARRAY_IFNULL, UNNEST for flattening; ANY/ EVERY/ SATISFIES for predicates inside arrays.

Mutations: UPDATE ... SET, UPSERT, MERGE INTO for conditional insert/update, and N1QL RETURNING to get the result document.

Use EXPLAIN to inspect the plan; a primary scan on the whole bucket signals a missing or unused secondary index.

Scope and collection (7.0+) provide logical isolation; collections share the bucket's memory quota and indexes are scoped to a collection.

SDK 3.x API: Cluster.connect(connectionString, options), then bucket(), scope(), collection(), and collection.get/upsert/remove.

GetResult exposes contentAs(type), cas, and expiry; check exists() before using content to avoid exceptions.

CAS (compare-and-swap) enables optimistic concurrency: pass the CAS to replace/replace with MutateInOptions; a mismatch throws CasMismatchException.

Durability: PersistTo / ReplicateTo (or DurabilityLevel MAJORITY / PERSIST_TO_MAJORITY) trade latency for crash safety.

Reactive and async APIs exist in Java, .NET, and Node.js; blocking calls are not safe on event-loop threads.

Kafka and other connectors use the same SDK; connection strings accept couchbase:// and couchbases:// (TLS).

Sub-document operations (lookupIn/mutateIn) modify parts of a document without fetching the whole body, reducing network cost.

Error handling: distinguish transient (retry with backoff), ambiguous (unknown outcome, re-read), and permanent (do not retry) failures.

Transactions (7.0+) use cluster.transactions().run with a lambda; operations inside are committed atomically across collections.

Services: data, index, query, search, analytics, eventing; each node can run a subset, and service placement affects failover capacity.

Rebalance moves vBuckets (1024 per bucket) to equalize data; during rebalance the cluster remains online but some requests are redirected.

Failover: hard failover removes a node immediately; graceful failover waits for data to be replicated first. Auto-failover triggers after a configured timeout.

Buckets have a RAM quota for caching and a replica count (0-3); replicas protect against node loss but not against application errors.

Backup: cbbackupmgr backup/restore supports incremental and merge; test restores regularly and store backups off-cluster.

Security: enable TLS (couchbases://), use RBAC roles (read-only, data reader/writer, query), and rotate credentials; never use the Administrator account in apps.

Monitoring: /pools/default endpoints, Prometheus exporter, and the UI show ops/sec, memory, disk write queue, and rebalance progress.

Upgrades: perform a rolling upgrade one node at a time, rebalancing after each, and verify version compatibility with SDKs and indexes.

Couchbase Lite is an embedded NoSQL database on device; Sync Gateway replicates between Lite and Couchbase Server via the replication protocol.

Replication is pull (server to device), push (device to server), or continuous; use continuous for live sync and one-shot for periodic sync.

Conflict resolution: default is last-write-wins by revision; custom resolvers can merge documents using the conflict handler.

Channels and roles control which documents sync to which users; a document must be in a channel the user can access.

Sync Gateway config defines databases, buckets, and sync function; the sync function assigns channels and validates writes.

Delta sync and compressed replication reduce bandwidth; enable them for mobile networks.

Couchbase Lite queries use N1QL-like SQL++ (or the older QueryBuilder); indexes on device improve local query performance.

Edge/offline apps must handle eventual consistency: design documents so merges are deterministic and avoid server-assigned keys.