CouchbaseStore

CouchbaseStore Reference documentation for the Couchbase store in the Prorm NoSQL layer. Source: couchbase · Tests: couchbase Overview Couchbase is a distributed document / key-value store. Documents live in a bucket, are addressed by an opaque key within a scope / collection, and can additionally be queried with N1QL (SQL++). CouchbaseStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle (connect / disconnect / isConnected / getClient) plus a native escape hatch. Because Couchbase does not fit the SQL-shaped Dialect interface (no identifier escaping, no DDL builder), the store exposes Couchbase's real key/value CRUD and N1QL query API directly rather than forcing everything through query(sql). Store metadata: The store uses the official couchbase Node.js SDK. That driver is an optional peer dependency — it is not a hard dependency of this module. It is loaded lazily via require('couchbase') inside connect(), so importing this module never requires the driver to be installed. A pre-built cluster may instead be supplied via the cluster option, in which case connect() uses it directly and skips loading the driver entirely (this is how the tests run with no driver and no network). Connection Real connection Internally, when no cluster is injected, connect() calls: If connecting fails, connect() resets the store to a disconnected state and throws a ConnectionError with the message Unable to connect to Couchbase: <parent message> (and database: 'couchbase'), preserving the original error as parent. Injected cluster (tests / custom wiring) Options Option | Type | Default | Purpose | --- | --- | --- | --- | connectionString | string | — | couchbase:// / couchbases:// endpoint. | username | string | — | Username for cluster authentication. | password | string | — | Password for cluster authentication. | bucket | string | 'default' | Default bucket for key/value operations. | scope | string | 'default' | Default scope within the bucket. | collection | string | 'default' | Default collection within the scope. | cluster | Cluster | — | Pre-built cluster to use instead of connecting via the driver. | The bucket / scope / collection defaults select which collection the key/value CRUD methods operate on when no explicit target is passed to collection(). Methods connect(): Promise<void> Establishes the cluster connection. Idempotent: if already connected with a live cluster, it returns immediately. Uses options.cluster when supplied, otherwise lazily requires couchbase and calls cb.connect(...). On failure, resets state and throws ConnectionError. disconnect(): Promise<void> Closes the cluster via cluster.close() and clears connection state. If there is no cluster, it simply marks the store disconnected. A close failure is wrapped in a DatabaseError (Couchbase disconnect failed: ...); the cluster reference and connected flag are cleared regardless. isConnected(): boolean Returns true only when the store is connected and holds a non-null cluster. getClient(): Cluster Returns the underlying native Cluster for operations not wrapped here. Throws ConnectionError (Not connected to Couchbase. Call connect() first.) if called before a successful connect(). collection(bucket?: string, scope?: string, collection?: string): Collection Resolves a collection handle. With no arguments (or only a bucket) it uses the store's configured defaults. If the resolved scope and collection are both the defaults (default / default), it returns bucket.defaultCollection(). Otherwise it targets a non-default collection via bucket.scope(scope).collection(collection). Requires a live connection (throws ConnectionError otherwise). Resolution failures are wrapped in DatabaseError (Couchbase collection resolution failed: ...). insert(id: string, doc: unknown): Promise<unknown> Inserts a new document at id; fails if the key already exists. Routes to collection().insert(id, doc). Returns the driver's mutation result. Errors are wrapped in DatabaseError (Couchbase insert failed: ...). upsert(id: string, doc: unknown): Promise<unknown> Inserts or replaces a document by key. Routes to collection().upsert(id, doc). Errors wrapped in DatabaseError (Couchbase upsert failed: ...). get(id: string): Promise<unknown> Fetches a document by key and returns its .content (the stored value), not the raw GetResult. Routes to collection().get(id) and returns result?.content. Errors wrapped in DatabaseError (Couchbase get failed: ...). replace(id: string, doc: unknown): Promise<unknown> Replaces an existing document; fails if the key does not exist. Routes to collection().replace(id, doc). Errors wrapped in DatabaseError (Couchbase replace failed: ...). remove(id: string): Promise<unknown> Removes a document by key. Routes to collection().remove(id). Errors wrapped in DatabaseError (Couchbase remove failed: ...). query(statement: string, options?: CouchbaseQueryOptions): Promise<unknown[]> Runs a N1QL / SQL++ statement against the cluster and returns its result rows (result?.rows ?? [], so an empty array when the driver returns none). options.parameters (unknown[] | Record<string, unknown>) binds positional (array) or named (object) parameters into the statement. It is destructured out and forwarded to the driver as { parameters, ...rest }, so any additional native query options are passed straight through: Requires a live connection (throws ConnectionError). Query errors are wrapped in DatabaseError (Couchbase query failed: ...). Error handling All CRUD, collection resolution, and query methods route driver failures through an internal wrapDatabaseError helper. A ConnectionError (e.g. "not connected") is passed through unchanged so callers can distinguish connection failures from operation failures; any other error becomes a DatabaseError that preserves the original message. Example Verification status Unit / mock-verified only. The tests in tests/nosql/couchbase.test.ts are pure unit tests: a mock cluster is injected via options.cluster, so connect() never loads the real couchbase driver and no network is touched. The couchbase package is not installed in this repository. Verified by the mock-backed tests: name / library metadata are 'couchbase'. Connect via injected cluster, isConnected(), getClient() returns the injected cluster, idempotent double-connect, clean disconnect() calling cluster.close() once. ConnectionError thrown by getClient(), CRUD, and query() before connecting. Default-collection resolution via bucket('app').defaultCollection(). insert / upsert / get / replace / remove routing to the matching collection method, with get returning .content. N1QL query forwarding statement + parameters to cluster.query and returning rows, defaulting to [] when the driver returns none. Driver errors from CRUD and query wrapped in DatabaseError. Not verified: behavior against a real Couchbase cluster, the lazy require('couchbase') driver path, real N1QL semantics, non-default scope/collection routing against a live server, and any network-level connection behavior. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories