SDKs, connectors & Couchbase Mobile

This section documents the current Couchbase Server 7.6.x line as published at the Couchbase Server documentation, which is the reference these pages are written and verified against. No specific patch version is pinned. Some capabilities (Enterprise-Edition-only Analytics, auditing, encryption at rest, the Backup service and rack-zone awareness, and Capella-only App Services and Columnar) are linked, not documented in depth.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production, as Couchbase iterates quickly.

This section’s bibliography lists the reference material consulted while preparing these pages.

Applications reach Couchbase through a language SDK; data-integration pipelines use the connectors; and offline-capable apps use Couchbase Mobile. All three speak the same KV, query, and DCP protocols the server exposes.

The SDK family

Couchbase publishes SDKs for Java, .NET, Node.js, Python, Go, C, PHP, Ruby, Scala, and Kotlin. Since the 3.x generation they share one API shape — the names and object model are the same across languages, so a pattern learned in one transfers:

  • Cluster — the connection to the whole cluster and the entry point for cluster-level work (SQL++ queries, Search, Analytics, management APIs).

  • Bucket → Scope → Collection — the data hierarchy; Collection carries the KV and sub-document operations.

  • Options objects (GetOptions, QueryOptions, …​) carry per-operation settings; a cluster environment carries process-wide defaults.

The connection string names seed nodes and the scheme: couchbase:// for plaintext, couchbases:// for TLS, optionally a DNS SRV hostname that expands to the seed list. Credentials and environment tuning go in ClusterOptions.

# Create the Cluster ONCE per process and share it. It is thread-safe, holds the
# connection pool, and refreshes the cluster map on topology changes.
Cluster cluster = Cluster.connect(
    "couchbases://db1.example.com,db2.example.com",
    ClusterOptions.clusterOptions("appuser", "s3cret").environment(env -> env
        .timeoutConfig(tc -> tc
            .kvTimeout(Duration.ofMillis(2500))
            .queryTimeout(Duration.ofSeconds(15)))
        .ioConfig(io -> io.numKvConnections(4))));

Bucket bucket = cluster.bucket("app");
bucket.waitUntilReady(Duration.ofSeconds(10));
Collection orders = bucket.scope("sales").collection("orders");
# https://docs.couchbase.com/java-sdk/current/howtos/managing-connections.html

Connection pooling is automatic: the SDK opens a small, fixed number of KV connections per node (numKvConnections, default 1) and multiplexes all operations over them, plus HTTP pools for Query/Search. Creating a Cluster per request instead of reusing one is the most common performance bug — each Cluster.connect re-runs discovery and rebuilds pools.

Timeouts are set per operation class (KV, query, view, management) with a default from the environment and an override on the options object. Every operation has a deadline; when it passes, the call fails with a TimeoutException.

The retry / error model splits failures in two:

  • Deterministic errors (DocumentNotFoundException, DocumentExistsException, CasMismatchException, auth failures) are returned immediately — retrying cannot change the outcome.

  • Transient errors (temporary out-of-memory, "not-my-vBucket" during a rebalance, connection blips) are retried automatically by the SDK’s best-effort retry strategy until the operation’s timeout.

try {
    GetResult r = orders.get("order:1");
} catch (DocumentNotFoundException e) {
    // deterministic -- handle "missing", do not retry
} catch (TimeoutException e) {
    // check e for the ambiguous/unambiguous distinction: an ambiguous timeout
    // on a write means it may or may not have been applied
}
# https://docs.couchbase.com/java-sdk/current/howtos/error-handling.html

Full driver list and per-language guides: Couchbase SDKs.

Big-data connectors

Purpose-built connectors move data between Couchbase and other systems using DCP, so they see every mutation in order:

  • Kafka connector — a Kafka Connect plugin. The source streams DCP mutations into Kafka topics; the sink writes Kafka records back into Couchbase. Kafka connector docs.

  • Spark connector — exposes buckets, collections, SQL++ queries, and DCP as Spark DataFrame/Dataset/DStream sources and sinks for batch and streaming jobs. Spark connector docs.

  • Elasticsearch connector — replicates documents from Couchbase into Elasticsearch indices via DCP, with checkpointing and restart. Elasticsearch connector docs.

# Kafka source connector: DCP mutations from one collection into a topic.
name=cb-orders-source
connector.class=com.couchbase.connect.kafka.CouchbaseSourceConnector
couchbase.seed.nodes=db1.example.com
couchbase.bucket=app
couchbase.scope=sales
couchbase.collections=sales.orders
couchbase.topic=cb.orders
# https://docs.couchbase.com/kafka-connector/current/index.html

Hand-rolling an Elasticsearch sync (polling for changes, pushing documents) is superseded on both ends: the Elasticsearch connector handles the streaming and checkpointing, and for search inside Couchbase the built-in Search service indexes the same documents with no second system to run — see Search, Analytics & Eventing.

Couchbase Mobile

Couchbase Mobile extends the database to phones, desktops, and edge devices with an embedded database that syncs back to a cluster.

Couchbase Lite

Couchbase Lite is a full database that runs in the application process (iOS, Android, Java, .NET, C, JavaScript/React Native). It stores JSON documents locally, works fully offline, and syncs when a connection is available.

# Couchbase Lite (Java) -- open a local database and do CRUD.
Database db = new Database("app");
Collection orders = db.createCollection("orders", "sales");

MutableDocument doc = new MutableDocument("order:1")
    .setString("status", "OPEN")
    .setDouble("total", 28.98);
orders.save(doc);

Document read = orders.getDocument("order:1");
# https://docs.couchbase.com/couchbase-lite/current/index.html

Queries use either SQL++ strings or the fluent QueryBuilder API; both run entirely on-device:

# SQL++ string form
Query q1 = db.createQuery(
    "SELECT META().id, total FROM sales.orders WHERE status = 'OPEN' ORDER BY total DESC");

# QueryBuilder form
Query q2 = QueryBuilder
    .select(SelectResult.expression(Meta.id), SelectResult.property("total"))
    .from(DataSource.collection(orders))
    .where(Expression.property("status").equalTo(Expression.string("OPEN")));

ResultSet rs = q1.execute();

Couchbase Lite also supports on-device full-text search (a MATCH index over document fields) and, in current releases, on-device vector search for similarity queries against locally stored embeddings — both run without a network round-trip.

The replicator moves changes between the local database and a Sync Gateway (or a peer). It is configured with an endpoint, a direction (push, pull, or both), continuous or one-shot mode, an authenticator, and the collections to sync:

ReplicatorConfiguration cfg = new ReplicatorConfiguration(
        new URLEndpoint(new URI("wss://sg.example.com:4984/app")))
    .addCollection(orders, null)
    .setType(ReplicatorType.PUSH_AND_PULL)
    .setContinuous(true)
    .setAuthenticator(new BasicAuthenticator("appuser", "s3cret".toCharArray()));

Replicator repl = new Replicator(cfg);
repl.addChangeListener(change -> { /* observe progress / errors */ });
repl.start();
# https://docs.couchbase.com/couchbase-lite/current/index.html

Sync Gateway

Sync Gateway is the server tier between Couchbase Lite clients and a Couchbase cluster. Its model:

  • Channels — every document is tagged with one or more channels; a client pulls only the channels it is granted. Channels are how a data set is partitioned per user or per tenant.

  • The sync function — a JavaScript function run on every incoming write. It validates the document, assigns it to channels, and grants users or roles access to channels.

  • Access control & authentication — users and roles live in Sync Gateway or an external provider (OIDC); the sync function’s requireUser / requireRole / access calls enforce per-document authorisation.

  • Replication & Delta Sync — clients replicate over WebSocket; Delta Sync sends only the changed fields of an updated document instead of the whole body, cutting bandwidth for large documents.

function (doc, oldDoc, meta) {
  if (!doc.region) { throw({forbidden: "missing region"}); }
  requireUser(doc.owner);
  channel("region-" + doc.region);
  access(doc.owner, "region-" + doc.region);
}
# https://docs.couchbase.com/sync-gateway/current/introduction.html

App Services, Edge Server & peer-to-peer

  • Capella App Services — the fully managed equivalent of Sync Gateway, run as part of Couchbase’s Capella cloud; same channel / sync-function / access model without operating the tier yourself.

  • Couchbase Edge Server — a lightweight single-node data + sync server for edge and on-premises sites (retail store, vehicle, factory floor). It serves a local REST API and replicates upstream to a cluster or App Services. Edge Server introduction.

  • Peer-to-peer sync — Couchbase Lite devices replicate directly to each other over a local network (one peer acts as listener, others connect) with no gateway, for collaboration that must keep working with no internet path.

For the API these mobile pieces sit under — SQL++, sub-document operations, the connection string — start from the Couchbase getting-started page, and compare the change-streaming model with MongoDB replica sets for the server-side side of sync.