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.0 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 6.5 as a developer preview). The Go 2.0 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.0.3

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 favourite 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)
	}

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("bucket-name")

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

The 2.0 SDK is ready for the introduction of Collections in an upcoming release of the Couchbase Data Platform. Couchbase Server 6.5 brings a limited Developer Preview of Collections, allowing Documents to be grouped by purpose or theme, according to a specified Collection.

	// get a collection reference
	collection := bucket.DefaultCollection()

	// for a named collection and scope
	// scope := bucket.Scope("my-scope")
	// collection := scope.Collection("my-collection")

The commented-out code shows how you would use a named collection and scope. However, in this case we’ve used the DefaultCollection, which provides the same functionality as bucket-level operations did in previous versions of Couchbase Server.

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

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

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.

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.