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 Beta release of the Couchbase Go SDK. The API interface is stable, but could change for bug fixes during the Beta process. New features are likely to be added.

Documentation is incomplete, subject to change, and could contain broken links.

The Couchbase Go SDK 3.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 introduces support for context.Context across all operations and improved error handling providing extra error information.

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-beta.1
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 1.12. 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:

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 {
		panic(err)
	}

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

	// get a bucket reference
	bucket := cluster.Bucket("travel-sample", nil)

	// get a collection reference
	collection := bucket.DefaultCollection()
	// for a named collection and scope
	// collection := bucket.Scope("my-scope").Collection("my-collection", &gocb.CollectionOptions{})

	// Upsert Document
	upsertResult, err := collection.Upsert("my-document", map[string]string{"name": "mike"}, &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)
}

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

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, err := collection.Upsert("my-document", map[string]string{"name": "mike"}, &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

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