Couchbase Go SDK 2.12

The Couchbase Go SDK allows Go applications to access a Couchbase cluster — Capella or self-managed.

Quickstart Guide | SDK Release Notes | Go SDK API Reference | Go SDK source code

What’s the point of a fast and scalable database if it’s not easy to develop for? Couchbase gives you the Go APIs to work with Capella, our managed solution, or self-managed options in your private Cloud or datacenter.

  • Data Ops (CRUD)

  • SQL++ Query (OLTP)

// Upsert with Durability level Majority
durableResult, err := collection.Upsert("document-key", &document, &gocb.UpsertOptions{
	DurabilityLevel: gocb.DurabilityLevelMajority,
})
query := "SELECT x.* FROM `travel-sample`.inventory.hotel x WHERE x.`city`= $1 LIMIT 10"
rows, err := cluster.Query(query, &gocb.QueryOptions{
	ScanConsistency:      gocb.QueryScanConsistencyRequestPlus,
	PositionalParameters: []interface{}{"San Francisco"},
	Adhoc:                true,
})
if err != nil {
	panic(err)
}
request := gocb.SearchRequest{
	VectorSearch: vector.NewSearch(
		[]*vector.Query{
			vector.NewQuery("vector_field", vectorQuery).NumCandidates(2).Boost(0.3),
			vector.NewQuery("vector_field", anotherVectorQuery).NumCandidates(5).Boost(0.7),
		}, nil,
	),
	SearchQuery: search.NewMatchAllQuery(),
}
vectorResult, err := scope.Search("vector-and-fts-index", request, nil)
if err != nil {
	panic(err)
}

Couchbase is a large platform — covering many services — and Couchbase SDKs are not thin wrappers generated around a REST API, but well thought out interfaces to the platform that make it easier to design and maintain your client code, and work with Couchbase in more natural ways for your platform. Install the SDK, and explore in the way that works best for you.

Installing the SDK
$ go get github.com/couchbase/gocb/v2

In line with the Golang project, we support both the current, and the previous, versions of Go. At time of writing (February 2026), this is 1.25 and 1.26. Older versions may remain compatible, but are not supported.

The links below will take you where you want to go — as will the navigation on the left-hand side of this page. But if you don’t know exactly where you need to go, try one of the following:

  • Our Quickstart Guide introduces the SDK with a quick install, and CRUD examples against the Data Service.

  • Couchbase’s familiar SQL-family query language and fuzzy search options (including vector search) are introduced on the Querying Your Data page.

  • The Go SDK docs are, necessarily, just a sub-set Go SDK API Reference — and a complete reference of all APIs can be found there.

  • For a fuller orientation, there is a guide to the Go SDK docs


Using Your Database

How-to guides to help you start your development journey with Couchbase and the Go SDK.

Easy to Connect & Get Started
Search, Query, Analyze
Lightning Fast Data Service
Observability & Error Handling


Resources

Useful resources to help support your development experience with Couchbase and the Go SDK.

Reference
Deployment



Couchbase Operational Cluster Feature Compatibility

All of the SDKs have API compatibility with most of the features in Couchbase Operational Clusters — whether self-managed, or Capella. The following table covers possible exceptions, and gives the version of the Go SDK and Couchbase Server with which some features were introduced.

Table 1. Couchbase Server and SDK Supported Version Matrix
Server 7.2 Server 7.6.x Server 8.0

KV Range Scan

N/A

From 2.7.0

Zone aware replica reads

N/A

From 2.9.2

Vector Search with Search Vector Index

N/A

From 2.8.0

Vector Query using Hyperscale Vector Index

N/A

From SDK 2.11.0 ①

Vector Query using Composite (GSI & vector) index

N/A

From SDK 2.11.0 ①

Distributed ACID Transactions

From 2.4.0

DNS SRV refresh for serverless environments (AWS Lambda, Azure Functions, and GCP Functions)

From 2.6.0

Circuit Breakers

From 2.0.0

OTel

From 2.12.0

Field Level Encryption

From 1.5.0

Cloud Native Gateway

From 2.7.0
1 As part of the standard SDK SQL++ API, it should be compatible with all earlier versions of the SDK — but it has not been tested.


Analytics SDKs

SDKs for Enterprise Analytics — Couchbase’s analytical database for real time apps and operational intelligence (RT-OLAP) — are available for the .NET, Go, Java, Node.js, and Python platforms. See the Enterprise Analytics SDK pages for more information.

Currently, different SDKs are needed to connect to Capella Analytics — as this service does not have Enterprise Analytics' load balancer, and uses a different connection protocol. Capella Analytics SDKs (also known as Columnar SDKs) are available for the Go, Java, Node.js, and Python platforms. See the Capella Analytics SDK pages for more information.