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, 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:
-
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.
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.