Managing Connections

      +
      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:

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

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

      #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:

      $ ./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:

      1. Set up your DNS server to respond properly from a DNS SRV request.

      2. Enable it on the SDK and point it towards the DNS SRV entry.