Install and Start Using the Go SDK with Couchbase Server

The Couchbase Go SDK allows you to connect to a Couchbase cluster from Go. It is a native Go library and uses the high-performance gocbcore to handle communicating to the cluster over Couchbase’s binary protocols

The Couchbase Go SDK 2.x is a complete rewrite of the API, reducing the number of overloads to present a simplified surface area, and adding support for future Couchbase Server features like Collections and Scopes (available in Couchbase Server 7.0). The Go 2.x SDK also introduces improved error handling providing extra error information.

If you’re upgrading your application from Couchbase Go SDK 1.x, please read our Migration Guide.

Installing the SDK

Version 2 of the Go SDK has added support for Go Modules. You can use go get to download the SDK:

$ go get github.com/couchbase/gocb/v2@v2.3.0

In line with the Golang project, we support both the current, and the previous, versions of Go. Currently we support using the Couchbase Go Client with Go releases 1.13 and up. Older versions may work, but are not supported.

Information on new features, fixes, and known issues — as well as information on how to install older release versions — is in the release notes.

Hello Couchbase

Now you have the Go client installed, open your preferred text editor and try out the following:

func main() {
	cluster, err := gocb.Connect(
		"localhost",
		gocb.ClusterOptions{
			Username: "Administrator",
			Password: "password",
		})
	if err != nil {
		panic(err)
	}

If you are connecting to Couchbase Capella rather than a local Couchbase Server, then also refer to the Cloud section, below.

Couchbase uses Role Based Access Control (RBAC) to control access to resources. Here we will use the Full Admin role created during installation of the Couchbase Data Platform. For production client code, you will want to use more appropriate, restrictive settings — but here we want to get you up and running quickly. If you’re developing client code on the same VM or machine as the Couchbase Server, your URI can be localhost.

To access the KV (Key/Value) API or to query views, you need to open a Bucket:

// get a bucket reference
bucket := cluster.Bucket(bucketName)

// We wait until the bucket is definitely connected and setup.
err = bucket.WaitUntilReady(5*time.Second, nil)
if err != nil {
	panic(err)
}

If you installed the travel sample data bucket, replace bucketName with travel-sample.

The 2.3 SDK supports full integration with the Collections feature in the latest release of the Couchbase Data Platform, Couchbase Server 7.0. This brings complete support of Collections, allowing Documents to be grouped by purpose or theme, according to a specified Scope. Here we will use the users collection within the tenant_agent_00 scope from travel-sample bucket as an example.

// get a user-defined collection reference
scope := bucket.Scope("tenant_agent_00")
collection := scope.Collection("users")

The code shows how you would use a named collection and scope. A named or default collection will provide the same functionality as bucket-level operations did in previous versions of Couchbase Server.

The DefaultCollection must be used when connecting to a 6.6 cluster or earlier.

// Upsert Document
upsertData := map[string]string{"name": "mike"}
upsertResult, err := collection.Upsert("my-document", upsertData, &gocb.UpsertOptions{})
if err != nil {
	panic(err)
}
fmt.Println(upsertResult.Cas())

// Get Document
getResult, err := collection.Get("my-document", &gocb.GetOptions{})
if err != nil {
	panic(err)
}

var myContent interface{}
if err := getResult.Content(&myContent); err != nil {
	panic(err)
}
fmt.Println(myContent)

KV Operations are described in detail on the KV Operations page. Now that you know the basics, you may wish to go straight to that page.

Cloud Connections

For developing on Couchbase Capella, try the Cloud-based Hello World program.

If you are not working from the same Availability Zone as your Capella instance, refer to the following:

Notes on Constrained Network Environments,
Network Requirements,
If you have a consumer-grade router which has problems with DNS-SRV records review our Troubleshooting Guide.

Additional Resources

The API reference is generated for each release and can be found here. Older API references are linked from their respective sections in the Release Notes.

The Migrating from SDK2 to 3 page highlights the main differences to be aware of when migrating your code.

Couchbase welcomes community contributions to the Go SDK. The Go SDK source code is available on GitHub.