A newer version of this documentation is available.

View Latest

Managing Connections using the Go SDK and Couchbase Server

    +
    This section describes how to connect the Go SDK to a Couchbase cluster. It contains best practices as well as information on TLS/SSL and other advanced connection options.

    Connecting to a Cluster

    A connection to a Couchbase Server cluster 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 gocb.Connect() with a connection string, username, and password:

    opts := gocb.ClusterOptions{
    	Username: "Administrator",
    	Password: "password",
    }
    cluster, err := gocb.Connect("10.112.193.101", opts)
    if err != nil {
    	panic(err)
    }
    If you are connecting to a version of Couchbase Server older than 6.5, it will be more efficient if the addresses are those of data (KV) nodes. You will in any case, with 6.0 and earlier, need to open a `Bucket instance before connecting to any other HTTP services (such as Query or Search.

    In a production environment, your connection string should include the addresses of multiple server nodes in case some are currently unavailable. Multiple addresses may be specified in a connection string by delimiting them with commas:

    opts := gocb.ClusterOptions{
    	Username: "Administrator",
    	Password: "password",
    }
    cluster, err := gocb.Connect("192.168.56.101,192.168.56.102", opts)
    if err != nil {
    	panic(err)
    }
    You don’t need to include the address of every node in the cluster. The client fetches the full address list from the first node it is able to contact.

    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?&kv_timeout=2500&query_timeout=60000

    The full list of recognized parameters is documented in the client settings reference.

    A connection string may optionally be prefixed by either "couchbase://" or "couchbases://". This can be used to control whether the SDK connects using encrypted connections or unencrypted connections.

    Connection Lifecycle

    All high-level objects in the Go SDK are designed to be safe for concurrent use by multiple goroutines. You will get the best performance by using only a single Cluster object per cluster, and as few Bucket, Scope and Collection as is reasonable for your application.

    We recommend creating a single Cluster instance when your application starts up, and sharing this instance throughout your application. If you know at startup time which buckets, scopes, and collections your application will use, we recommend obtaining them from the Cluster at startup time and sharing those instances throughout your application as well.

    Before your application stops, gracefully shut down the client by calling the Close() method of each Cluster you created.

    Alternate Addresses and Custom Ports

    If your Couchbase Server cluster is running in a containerized, port mapped, or otherwise NATd 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.

    On the server side, each server node must be configured to advertise its external address as well as any custom port mapping. This is done with the setting-alternate-address CLI command introduced in Couchbase Server 6.5. A node configured in this way will advertise two addresses: one for connecting from the same network, and another for connecting from an external network.

    On the client side, the externally visible ports must be used when connecting. If the external ports are not the default, you can specify custom ports as part of your connection string.

    opts := gocb.ClusterOptions{
    	Username: "Administrator",
    	Password: "password",
    }
    cluster, err := gocb.Connect("couchbase://192.168.56.101:1234,192.168.56.102:5678", opts)
    if err != nil {
    	panic(err)
    }
    In a deployment that uses multi-dimensional scaling, a custom KV port is only applicable for nodes running the KV service. A custom manager port may be specified regardless of which services are running on the node.

    In many cases the client is able to automatically select the correct set of addresses to use when connecting to a cluster that advertises multiple addresses. If the detection heuristic fails in your environment, you can override it by setting the network_type client setting to default if the client and server are on the same network, or external if they’re on different networks.

    Any TLS certificates must be set up at the point where the connections are being made.

    Secure Connections

    Couchbase Server Enterprise Edition supports full encryption of client-side traffic using Transport Layer Security (TLS). That includes key-value type operations, queries, and configuration communication. Make sure you have the Enterprise Edition of Couchbase Server before proceeding with configuring encryption on the client side.

    To configure encryption for the Go SDK:

    1. Get the CA certificate from the cluster and save it in a text file.

    2. Enable encryption on the client side and point it to the file containing the certificate.

    It is important to make sure you are transferring the certificate in an encrypted manner from the server to the client side, so either copy it through SSH or through a similar secure mechanism.

    If you are running on localhost and just want to enable TLS for a development machine, just copying and pasting it suffices. Navigate in the admin UI to Settings  Cluster and copy the input box of the TLS certificate into a file on your machine (which we will refer to as cluster.cert). It looks similar to this:

    -----BEGIN CERTIFICATE-----
    MIICmDCCAYKgAwIBAgIIE4FSjsc3nyIwCwYJKoZIhvcNAQEFMAwxCjAIBgNVBAMT
    ASowHhcNMTMwMTAxMDAwMDAwWhcNNDkxMjMxMjM1OTU5WjAMMQowCAYDVQQDEwEq
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzz2I3Gi1XcOCNRVYwY5R
    ................................................................
    mgDnQI8nw2arBRoseLpF6WNw22CawxHVOlMceQaGOW9gqKNBN948EvJJ55Dhl7qG
    BQp8sR0J6BsSc86jItQtK9eQWRg62+/XsgVCmDjrB5owHPz+vZPYhsMWixVhLjPJ
    mkzeUUj/kschgQ0BWT+N+pyKAFFafjwFYtD0e5NwFUUBfsOyQtYV9xu3fw+T2N8S
    itfGtmmlEfaplVGzGPaG0Eyr53g5g2BgQbi5l5Tt2awqhd22WOVbCalABd9t2IoI
    F4+FjEqAEIr1mQepDaNM0gEfVcgd2SzGhC3yhYFBAH//8W4DUot5ciEhoBs=
    -----END CERTIFICATE-----

    The next step is to enable encryption and pass it the path to the certificate file.

    // We use the system certificate pool here and assume the Couchbase root certificate(s) have
    // been installed there, but it is also possible to load these from a file.
    rootCAs, err := x509.SystemCertPool()
    if err != nil {
    	panic(err)
    }
    
    opts := gocb.ClusterOptions{
    	Username: "Administrator",
    	Password: "password",
    	SecurityConfig: gocb.SecurityConfig{
    		TLSRootCAs: rootCAs,
    	},
    }
    cluster, err := gocb.Connect("couchbases://10.112.193.101", opts)
    if err != nil {
    	panic(err)
    }

    If you want to verify it’s actually working, you can use a tool like tcpdump. For example, an unencrypted upsert request looks like this (using sudo tcpdump -i lo0 -A -s 0 port 11210):

    E..e..@.@.............+......q{...#..Y.....
    .E...Ey........9........................id{"key":"value"}

    After enabling encryption, you cannot inspect the traffic in cleartext (same upsert request, but watched on port 11207 which is the default encrypted port):

    E.....@.@.............+....Z.'yZ..#........
    ..... ...xuG.O=.#.........?.Q)8..D...S.W.4.-#....@7...^.Gk.4.t..C+......6..)}......N..m..o.3...d.,.	...W.....U..
    .%v.....4....m*...A.2I.1.&.*,6+..#..#.5

    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.

    Your DNS server should be set up like this (one row for each bootstrap node):

    _couchbase._tcp.example.com.  3600  IN  SRV  0  0  11210  node1.example.com.
    _couchbase._tcp.example.com.  3600  IN  SRV  0  0  11210  node2.example.com.
    _couchbase._tcp.example.com.  3600  IN  SRV  0  0  11210  node3.example.com.
    The ordering, priorities, and weighting are completely ignored and should not be set on the records to avoid ambiguities.

    If you plan to use secure connections, you use _couchbases instead:

    _couchbases._tcp.example.com.  3600  IN  SRV  0  0  11207  node1.example.com.
    _couchbases._tcp.example.com.  3600  IN  SRV  0  0  11207  node2.example.com.
    _couchbases._tcp.example.com.  3600  IN  SRV  0  0  11207  node3.example.com.

    DNS SRV bootstrapping is available in the Go SDK. In order to make the SDK actually use the SRV records, you need to enable DNS SRV on the environment and pass in the host name from your records (here example.com):

    opts := gocb.ClusterOptions{
    	Username: "Administrator",
    	Password: "password",
    }
    cluster, err := gocb.Connect("couchbase://mysrvrecord.hostname.com", opts)
    if err != nil {
    	panic(err)
    }

    If the DNS SRV records could not be loaded properly you’ll get the exception logged and the given host name will be used as a A record lookup.

    Also, if you pass in more than one node, DNS SRV bootstrap will not be attempted.