Connecting through a Cloud Native Gateway instead of directly to cluster nodes.

A connection string with the couchbase2:// scheme routes every operation over gRPC to a single Cloud Native Gateway (CNG) endpoint, rather than opening MCBP and HTTP connections to each node of a cluster. The gateway performs the routing the library would otherwise do itself.

The public API is the same one used for couchbase:// and couchbases://. No type or method is specific to this transport; what changes is which operations a cluster can serve, and how a connection string is written.

Warning: The transport as a whole carries the stability level of this page. Individual API entities keep their own stability, which this page does not lower: get is committed whether it runs over couchbase:// or couchbase2://. What is uncommitted is the behaviour of running it over this transport at all.

Enabling it

Support is a compile-time option and is off by default. A library built without COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2 refuses a couchbase2:// connection string, reporting feature_not_available from connect rather than attempting a handshake the gateway cannot answer.

Writing the connection string

The scheme implies TLS: a couchbase2:// connection is always encrypted, and the default port is 18098. Neither is inferred from the scheme name, so an endpoint published on another port must say so explicitly, and a private certificate authority must be trusted as it would be for couchbases://.

Two further rules apply to couchbase2:// that do not apply to the other schemes:

Exactly one host. The gateway fronts the whole cluster, so there is no node list to rotate through. A string naming several hosts still connects, to a single one of them: the bootstrap list is shuffled unless preserve_bootstrap_nodes_order is set, so which one is not predictable from the order they were written in. The log records the endpoint chosen and that the rest were ignored.
No bootstrap-mode suffix on the host, since the gateway uses neither MCBP nor HTTP config bootstrap. A suffix is ignored.

Operations the library refuses

These report feature_not_available without reaching the gateway, because the transport has no way to carry them:

ping, ping and diagnostics – there are no per-node or per-bucket sessions to probe.
get_all_replicas, get_any_replica, lookup_in_all_replicas and lookup_in_any_replica.
Subdocument operations against the active node, lookup_in and mutate_in.
Requests carrying an option or a value the transport has no equivalent for, across query, analytics, search, views and management – a memcached bucket, for instance. The refusal depends on what the request carries rather than on the operation, so the same call may be served or refused according to how it was built.

Operations that fail without being refused

Two things are not served either, but do not report feature_not_available and are not turned away before work begins. Both need the bucket configuration and the per-node connections this transport does not open, so they fail on that path instead, and the error describes that failure rather than the missing feature.

The first is scan.

The second is poll-based durability, and it is the one to know about, because the mutation is already applied by the time it fails.

It is requested by passing persist_to and replicate_to to common_durability_options. The mutation is sent to the gateway and applied, and only the polling that follows fails, so the document is already written when the error arrives and the durability it asked for has not been established.

Level-based durability, requested with a durability_level, is served normally and is the durability to use over this transport.

Anything not listed above is sent to the gateway, which decides whether it can serve it. An operation the gateway does not implement is reported in the gateway's own terms, so the set of working operations depends on the gateway version as well as on this library.

Since: 1.4.0 – Cloud Native Gateway (CNG, couchbase2://) support

Uncommitted: Cloud Native Gateway (CNG, couchbase2://) support is uncommitted and may change in a future release, independently of the stability of the API it applies to