You are viewing the documentation for a prerelease version.

View Latest

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
These pages cover the alpha of the Couchbase Go SDK — 2.0 alpha. As such they are likely to change without notice. The alpha code should not be used in production.

Installing the SDK

Version 2 of the Go SDK has added support for Go Modules. If you are using Go 1.11.1+ with modules enabled and setup then you can use go get:

$ go get github.com/couchbase/gocb/v2@v2.0.0-alpha.5
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.12 and 1.11. Older versions may work, but are not supported.

To use an older version of Go, for now, you will need to manually clone the repository:

$ git clone https://github.com/couchbase/gocb/ $GOPATH/src/github.com/couchbase/gocb
$ cd $GOPATH/src/github.com/couchbase/gocb
$ git checkout v2.0.0-alpha.5

There is no need to run go get because of the inclusion of the vendor directory, which is created using the version information from the Go SDK go.mod file.

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:

import (
	"fmt"

	gocb "github.com/couchbase/gocb/v2"
)

func main() {
	opts := gocb.ClusterOptions{
		Authenticator: gocb.PasswordAuthenticator{
			"Administrator",
			"password",
		},
	}
	cluster, err := gocb.Connect("localhost", opts)
	if err != nil {
		// handle 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.

Connection to the cluster is initialized by:

// get a bucket reference
bucket := cluster.Bucket("bucket-name", &gocb.BucketOptions{})

If you installed the travel sample data bucket, substitute travel-sample for bucket-name.

// get a bucket reference
bucket := cluster.Bucket("travel-sample", &gocb.BucketOptions{})

The 2.0 SDK is ready for the introduction of Collections in an upcoming release of the Couchbase Data Platform. The latest release, Mad Hatter, brings a limited Developer Preview of Collections, allowing Documents to be grouped by purpose or theme, according to specified Scope. Here we’ve used the DefaultCollection, which covers the whole Bucket.

// Upsert Document
upsertResult, _ := collection.Upsert("my-document", map[string]string{"name": "mike"}, &gocb.UpsertOptions{})
fmt.Println(upsertResult)

// Get Document
getResult, _ := collection.Get("my-document", &gocb.GetOptions{})
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

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