Start Using the Go SDK

  • tutorial
    +
    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:

    • Couchbase Capella Sample

    • Local Couchbase Server

    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)
    	}
    }
    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 := "localhost"
    	bucketName := "travel-sample"
    	username := "Administrator"
    	password := "password"
    
    	// For a secure cluster connection, use `couchbases://<your-cluster-ip>` instead.
    	cluster, err := gocb.Connect("couchbase://"+connectionString, gocb.ClusterOptions{
    		Authenticator: gocb.PasswordAuthenticator{
    			Username: username,
    			Password: password,
    		},
    	})
    	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")
    
    	type User struct {
    		Name      string   `json:"name"`
    		Email     string   `json:"email"`
    		Interests []string `json:"interests"`
    	}
    
    	// Create and store a Document
    	_, 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{Adhoc: true},
    	)
    	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)
    	}
    }

    As well as the Go SDK (see below), and a running instance of Couchbase Server, you will need to load up the Travel Sample Bucket using either the Web interface or the command line.

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

    Prerequisites

    The following code samples assume:

    • Couchbase Capella

    • Couchbase Server

    • 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 by the Capella free trial.

    • 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 database 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.
    • You have initalised a Go module, and have a go.mod file in your working directory.

    • Couchbase Server is installed and accessible locally.

    • You have created your own bucket, or loaded the Travel Sample dataset using the Web interface.

    • A user is created with permissions to access your cluster (at least Application Access permissions). See Manage Users, Groups and Roles for more details.

    Couchbase Server uses Role Based Access Control (RBAC) to control access to resources. In this guide we suggest using the Full Admin role created during setup of your local Couchbase Server cluster. For production client code, you will want to use more appropriate, restrictive settings.

    Quick Installation

    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

    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:

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

    Now, create an empty main() function.

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

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

    • Couchbase Capella

    • Local Couchbase Server

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

    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

    • Local Couchbase Server

    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.

    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.
    // For a secure cluster connection, use `couchbases://<your-cluster-ip>` instead.
    cluster, err := gocb.Connect("couchbase://"+connectionString, gocb.ClusterOptions{
    	Authenticator: gocb.PasswordAuthenticator{
    		Username: username,
    		Password: password,
    	},
    })
    if err != nil {
    	log.Fatal(err)
    }

    For developing locally on the same machine as Couchbase Server, your URI can be couchbase://localhost as shown here. For production deployments, you will want to use a secure server, with couchbases://.

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

    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.

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

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

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

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

    $ go run main.go

    The results you should expect are as follows:

    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