January 19, 2025
+ 12
A quick start guide to get you up and running with Couchbase and the Go SDK.

In this guide, you will learn:

Hello Couchbase

We will go through the code sample step by step, but for those in a hurry to see it, here it is:

To connect to Couchbase Capella, be sure to get the correct endpoint as well as user, password and bucket name.

package main

import (
	"fmt"
	"log"
	"time"

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


func main() {
	// Uncomment following line to enable logging
	// gocb.SetLogger(gocb.VerboseStdioLogger())

	// Update this to your cluster details
	connectionString := "cb.<your-endpoint>.cloud.couchbase.com"
	bucketName := "travel-sample"
	username := "username"
	password := "Password!123"

	options := gocb.ClusterOptions{
		Authenticator: gocb.PasswordAuthenticator{
			Username: username,
			Password: password,
		},
	}

	// Sets a pre-configured profile called "wan-development" to help avoid latency issues
	// when accessing Capella from a different Wide Area Network
	// or Availability Zone (e.g. your laptop).
	if err := options.ApplyProfile(gocb.ClusterConfigProfileWanDevelopment); err != nil {
		log.Fatal(err)
	}

	// Initialize the Connection
	cluster, err := gocb.Connect("couchbases://"+connectionString, options)
	if err != nil {
		log.Fatal(err)
	}

	bucket := cluster.Bucket(bucketName)

	err = bucket.WaitUntilReady(5*time.Second, nil)
	if err != nil {
		log.Fatal(err)
	}

	// Get a reference to the default collection, required for older Couchbase server versions
	// col := bucket.DefaultCollection()

	col := bucket.Scope("tenant_agent_00").Collection("users")

	// Create and store a Document
	type User struct {
		Name      string   `json:"name"`
		Email     string   `json:"email"`
		Interests []string `json:"interests"`
	}

	_, err = col.Upsert("u:jade",
		User{
			Name:      "Jade",
			Email:     "jade@test-email.com",
			Interests: []string{"Swimming", "Rowing"},
		}, nil)
	if err != nil {
		log.Fatal(err)
	}

	// Get the document back
	getResult, err := col.Get("u:jade", nil)
	if err != nil {
		log.Fatal(err)
	}

	var inUser User
	err = getResult.Content(&inUser)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("User: %v\n", inUser)

	// Perform a N1QL Query
	inventoryScope := bucket.Scope("inventory")
	queryResult, err := inventoryScope.Query(
		fmt.Sprintf("SELECT * FROM airline WHERE id=10"),
		&gocb.QueryOptions{},
	)
	if err != nil {
		log.Fatal(err)
	}

	// Print each found Row
	for queryResult.Next() {
		var result interface{}
		err := queryResult.Row(&result)
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(result)
	}

	if err := queryResult.Err(); err != nil {
		log.Fatal(err)
	}
}

The Couchbase Capella free tier version comes with the Travel Sample Bucket, and its Query indexes, loaded and ready.

Prerequisites

The following code samples assume:

  • You have initalised a Go module, and have a go.mod file in your working directory.

  • You have signed up to Couchbase Capella.

  • You have created your own bucket, or loaded the Travel Sample dataset. Note, the Travel Sample dataset is installed automatically when deploying a Capella free tier cluster.

  • A user is created with permissions to access the cluster (at least Application Access permissions). See the Capella connection page for more details.

Couchbase Capella uses Roles to control user access to cluster resources. For the purposes of this guide, you can use the Organization Owner role automatically assigned to your account during installation of the Capella cluster. In a production scenario, we strongly recommend setting up users with more granular access roles as a best practice.

Quick Installation

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

console
$ go get github.com/couchbase/gocb/v2

More details on installation can be found here.

In line with the Golang project, we support both the current, and the previous, versions of Go.

Step by Step

Create an empty file named main.go and walk through adding code step-by-step.

Here are all the imports needed to run the sample code:

golang
package main import ( "fmt" "log" "time" "github.com/couchbase/gocb/v2" )

Now, create an empty main() function.

golang
func main() { // add code here... }

In your main() function, add the following variables and update them accordingly:

golang
// Update this to your cluster details connectionString := "cb.<your-endpoint>.cloud.couchbase.com" bucketName := "travel-sample" username := "username" password := "Password!123"

Connect

Connect to your cluster by calling the Cluster.Connect() function and pass it your connection details. The basic connection details that you’ll need are given below — for more background information, see Managing Connections.

Couchbase Capella requires mandatory use of TLS (Transport Layer Security). As of Go SDK version 2.5.0, the standard certificate required to connect to a Capella cluster is automatically included with no additional configuration.

golang
options := gocb.ClusterOptions{ Authenticator: gocb.PasswordAuthenticator{ Username: username, Password: password, }, } // Sets a pre-configured profile called "wan-development" to help avoid latency issues // when accessing Capella from a different Wide Area Network // or Availability Zone (e.g. your laptop). if err := options.ApplyProfile(gocb.ClusterConfigProfileWanDevelopment); err != nil { log.Fatal(err) } // Initialize the Connection cluster, err := gocb.Connect("couchbases://"+connectionString, options) if err != nil { log.Fatal(err) }

When accessing Capella from a different Wide Area Network or Availability Zone, you may experience latency issues with the default connection settings. SDK 2.6 introduces a wan-development Configuration Profile, which provides pre-configured timeout settings suitable for working in high latency environments. Basic usage is shown in the example above, but if you want to learn more see Constrained Network Environments.

The Configuration Profiles feature is currently a Volatile API and may be subject to change.

Following successful authentication, add this code snippet to access your Bucket:

golang
bucket := cluster.Bucket(bucketName) err = bucket.WaitUntilReady(5*time.Second, nil) if err != nil { log.Fatal(err) }

Add and Retrieve Documents

The Go SDK supports full integration with the Collections feature introduced in Couchbase Server 7.0. Collections allow documents to be grouped by purpose or theme, according to a specified Scope.

Here we refer to the users collection within the tenant_agent_00 scope from the Travel Sample bucket as an example, but you may replace this with your own data.

golang
// Get a reference to the default collection, required for older Couchbase server versions // col := bucket.DefaultCollection() col := bucket.Scope("tenant_agent_00").Collection("users")
For Local Couchbase Server only

The DefaultCollection must be used when connecting to a 6.6 cluster or earlier — see comment in the code snippet above.

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.

Data operations, such as storing and retrieving documents, can be done using Collection.Upsert() and Collection.Get().

Add the following code to create a new document:

golang
// Create and store a Document type User struct { Name string `json:"name"` Email string `json:"email"` Interests []string `json:"interests"` } _, err = col.Upsert("u:jade", User{ Name: "Jade", Email: "jade@test-email.com", Interests: []string{"Swimming", "Rowing"}, }, nil) if err != nil { log.Fatal(err) }

Now, let’s retrieve it using a key-value (data) operation.

golang
// Get the document back getResult, err := col.Get("u:jade", nil) if err != nil { log.Fatal(err) } var inUser User err = getResult.Content(&inUser) if err != nil { log.Fatal(err) } fmt.Printf("User: %v\n", inUser)

SQL++ Lookup

Couchbase SQL++ queries are performed by invoking Cluster.Query() or Scope.Query.

Cluster level queries require you to specify the fully qualified keyspace each time (e.g. travel-sample.inventory.airline). However, with a Scope level query you only need to specify the Collection name — which in this case is airline:

golang
// Perform a N1QL Query inventoryScope := bucket.Scope("inventory") queryResult, err := inventoryScope.Query( fmt.Sprintf("SELECT * FROM airline WHERE id=10"), &gocb.QueryOptions{}, ) if err != nil { log.Fatal(err) } // Print each found Row for queryResult.Next() { var result interface{} err := queryResult.Row(&result) if err != nil { log.Fatal(err) } fmt.Println(result) } if err := queryResult.Err(); err != nil { log.Fatal(err) }

You can learn more about SQL++ queries on the Query page.

Execute!

Now we can run our code using the following command:

console
$ go run main.go

The results you should expect are as follows:

console
User: {Jade jade@test-email.com [Swimming Rowing]} map[airline:map[callsign:MILE-AIR country:United States iata:Q5 icao:MLA id:10 name:40-Mile Air type:airline]]

Next Steps

Now you’re up and running, try one of the following:

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 API (Go 1.x) to API 3 page (Go 2.x SDK) 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.

Troubleshooting

Output