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")

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.

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.

Configuring SSL

Be aware that certificate validation when connecting to Couchbase using SSL requires Go 1.6+ and gocb 1.2+. Otherwise SSL connections are subject to man-in-the-middle attacks.

To configure SSL, pass an SSL scheme with your connection string when creating your cluster object.

myCluster, _ := gocb.Connect("couchbases://10.1.1.1")
myBucket, _ := myCluster.OpenBucket("default", "")

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.