A newer version of this documentation is available.

View Latest

Managing Connections Using the Go SDK with Couchbase Server

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

    Creating a Cluster Object

    The Cluster object serves as an organizational unit for any Bucket objects created. As on the server each bucket is a member of a cluster, likewise in the SDK each Bucket object is a child of a Cluster. To create a cluster, construct it using a connection string, specifying the scheme and host(s) to connect to gocb.Connect:

    cluster, err := gocb.Connect("couchbase://localhost")

    Any Cluster node host addresses passed in to establish (bootstrap) the connection should be for data (KV) nodes. You can also specify multiple hosts in the connection string by separating each host with a comma:

    cluster, err := gocb.Connect("couchbase://host1,host2,host3,hostN")

    Specifying multiple hosts may add additional redundancy when bootstrapping.

    From Couchbase Go SDK 1.4.0, AlternateAddress is implemented, for connecting to nodes in a NATed environment, such as Docker containers using portmapping. It is on by default, if the server provides a topology that includes a multi-network configuration. Whichever network is selected at bootstrap will be logged.

    Note that any SSL/TLS certificates must be set up at the point where the connections are being made. The Couchbase SDKs will honor any valid SSL/TLS certificates.

    Authenticating

    From Couchbase Server 5.0, you will need to authenticate the user, rather than against the bucket, as part of Role-Based Access Control. You will need to use PasswordAuthenticator:

    cluster.Authenticate(gocb.PasswordAuthenticator{
         Username: username,
         Password: password,
     })

    Opening a Bucket

    Once the Cluster object has been created, you may open one or more Bucket objects using Cluster.OpenBucket. The first argument is the bucket name to use, and the second is the bucket password - which should be provided if the bucket is password protected, or supplied as nil otherwise.

    bucket1, err := cluster.OpenBucket("messages", nil)
    protectedBucket, err := cluster.OpenBucket("protected", "s3cr3t")

    Note that the bucket password is not the administrative password used to access the Couchbase Web UI.

    Once the bucket has been created, it may be used throughout your application. Buckets are thread-safe and need not be locked or otherwise protected to be used from multiple threads.

    You should only need to open one Bucket object for each Couchbase Bucket in your application, and you should attempt to keep the Bucket object available and open for as long as you plan to access Couchbase within your application.

    Connection Limits

    Each Couchbase Data node allows by default, in Couchbase Data Platform 6.0 and earlier, up to 30,000 concurrent key-value connections per port exposed to the user by the Data Service (ports 11210 and 11207). This means that if you are mixing SSL connections (port 11207) and plain connections (port 11210), you can have 30,000 connections on each of these two ports, or up to 60,000 in total. If you are using plain (or SSL) alone, then the limit is 30,000.

    From 6.5 onwards, the default value is 65,000 connections to the server — with 5000 of these reserved for system use. Thus, you can use 60,000 connections even if you only use_ one_ of the two ports (plain or SSL).

    Closing a Bucket

    When your application is done talking to Couchbase, you can issue the Bucket.Close() call on the bucket, which will disconnect your application from the given bucket.

    Secure Connections with TLS

    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 — so long as you use 127.0.0.1 rather than localhost in the connection string. This is because the certificate will not match the name localhost.

    Navigate in the admin UI to Settings  Cluster and copy the input box of the TLS certificate into a file on your machine. 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.

    myCluster, _ := gocb.Connect("couchbases://10.1.1.1?cacertpath=/path/to/ca.pem")
    
    cluster.Authenticate(gocb.PasswordAuthenticator
         {      Username: username,      Password: password, }
         )
    
    myBucket, _ := myCluster.OpenBucket("default", "")

    If you want to verify that 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.

    To use DNS SRV in the Go SDK, simply pass the single bootstrap node (in this case couchbase://example.com). DNS SRV lookup will not be performed if there is more than a single node in the bootstrap list.

    Cloud Connections

    Connecting to couchbase Cloud requires TLS and DNs-SRV, as detailed above. Additionally, if you are using a private network, for Go SDK 1.6.x you will need to set network=default in the connection string.