Managing Connections

March 23, 2025

+ 12

This section describes how to connect the C++ SDK to a Couchbase cluster. It contains best practices as well as information on TLS/SSL and advanced connection options, and a sub-page on troubleshooting Cloud connections.

Our Getting Started pages cover the basics of making a connection to a Capella or self-managed Couchbase cluster. This page is a wider look at the topic.

Connecting to a Cluster

A connection to a Couchbase cluster — on Capella, or self-managed — is represented by a cluster object. A cluster provides access to buckets, scopes, and collections, as well as various Couchbase services and management interfaces. The simplest way to create a cluster object is to call couchbase::cluster::connect() with a connection string, username, and password:

c++
ViewCopy
auto [err, cluster] = couchbase::cluster::connect(connection_string, options).get();

And here it is in the context of a full connection lifecycle:

c++
ViewCopy
#include <couchbase/cluster.hxx>
#include <couchbase/fmt/error.hxx>

#include <iostream>

int
main(int argc, const char* argv[])
{
    if (argc != 4) {
        fmt::println("USAGE: ./start_using couchbase://127.0.0.1 Administrator password");
        return 1;
    }

    std::string connection_string{ argv[1] }; // "couchbase://127.0.0.1"
    std::string username{ argv[2] };          // "Administrator"
    std::string password{ argv[3] };          // "password"
    std::string bucket_name{ "travel-sample" };

    auto options = couchbase::cluster_options(username, password);
    // customize through the 'options'.
    // For example, optimize timeouts for WAN
    options.apply_profile("wan_development");

    // [1] connect to cluster using the given connection string and the options
    auto [err, cluster] = couchbase::cluster::connect(connection_string, options).get();
    if (err) {
        fmt::println("Unable to connect to the cluster: {}", err);
        return 1;
    }

    // get a bucket reference
    auto bucket = cluster.bucket(bucket_name);

    // get a user-defined collection reference
    auto scope = bucket.scope("tenant_agent_00");
    auto collection = scope.collection("users");

    { // your database interactions here
    }

    // close cluster connection
    cluster.close().get();
    return 0;
}

If this were compiled as start_using, then the connection string and authentication credentials would be passed as arguments to the command like so:

console
Copy
$ ./start_using couchbase://127.0.0.1 Administrator password

Here we’re talking to a local development cluster. For Capella, this will need couchbases:// for TLS, followed by your Capella cluster name — see Connect To Your Cluster. The client certificate for connecting to Capella is included in the C++ SDK installation.

Connection Strings

A Couchbase connection string is a comma-delimited list of IP addresses and/or hostnames, optionally followed by a list of parameters.

The parameter list is just like the query component of a URI; name-value pairs have an equals sign (=) separating the name and value, with an ampersand (&) between each pair. Just as in a URI, the first parameter is prefixed by a question mark (?).

Simple connection string with one seed node

127.0.0.1

Connection string with two seed nodes

nodeA.example.com,nodeB.example.com

Connection string with two parameters

127.0.0.1?network=external&key_value_timeout=10s

For the C++ SDK and its wrapper SDKs, this is the main method of passing client options, such as timeout options or I/O options. For more details see Client Settings, or the latest, complete listing in the [API Reference].

Secure Connections

Couchbase Server Enterprise Edition and Couchbase Capella support full encryption of client-side traffic using Transport Layer Security (TLS).

Dealing With Network Latency

Working in the Cloud

We strongly recommend that the client and server are in the same LAN-like environment (e.g. AWS Region). As this may not always be possible during development, read the guidance on working with constrained network environments. More details on connecting your client code to Couchbase Capella can be found in the Cloud docs.

If you are connecting from IPv6-only environment, you cannot connect to Couchbase Capella as you are unable to use the IPv4 records published for Capella clusters.

Troubleshooting Connections to Cloud

Some DNS caching providers (notably, home routers) can’t handle an SRV record that’s large — if you have DNS-SRV issues with such a set-up, reduce your DNS-SRV to only include three records. [For development only, not production.]. Our Troubleshooting Cloud Connections page will help you to diagnose this and other problems — as well as introducing the SDK doctor tool.

Complex Environments

Alternate Addresses and Custom Ports

If your Couchbase Server cluster is running in a containerized, port mapped, or otherwise NAT’d environment like Docker or Kubernetes, a client running outside that environment may need additional information in order to connect the cluster. Both the client and server require special configuration in this case.

Using DNS SRV records

As an alternative to specifying multiple hosts in your program, you can get the actual bootstrap node list from a DNS SRV record. The following steps are necessary to make it work:

Set up your DNS server to respond properly from a DNS SRV request.
Enable it on the SDK and point it towards the DNS SRV entry.