I’m pleased to announce the Couchbase Go SDK 2.0 Alpha. This new SDK brings in a series of changes across all of the Couchbase SDKs that the team has been putting together. The new SDKs bring a completely new API which is simpler, future proof and integrates with the latest ecosystem developments.<\/p>\n
Version 2.0 of the Go SDK aligns with new features to Couchbase Server that extend off of the traditional Bucket interface: support for Scopes and Collection. Additionally, it consolidates and refines the interface – improving cross-SDK conformance.<\/p>\n
In previous Couchbase Server versions Buckets were used as logical, user-named entities that group items. This allowed them to be accessed, indexed, replicated, and access-controlled. This was really the only means of achieving multi-tenancy using Couchbase Server and came with some limitations: Buckets themselves are fairly resource intensive and a cluster can only efficiently manage a finite number of buckets. For modern micro-service architectures, or really any architecture where multi-tenancy was needed, this made for some challenges when serving a large amount of tenants. This is solved in a future version of Couchbase Server by the concepts of Scopes and Collections.<\/p>\n
A Scope represents a unit of multi tenancy and is built of Collections. A Collection is effectively a unique name for a group of documents. Within a Scope a Collection name must be unique, but the same Collection name can be used across multiple Scopes. Every Bucket contains a default Scope with the name \u201c_default\u201d with an identifier of 0 (zero) which contains a default Collection named \u201c_default\u201d with its accompanying identifier of 0 (zero).<\/p>\n
This has the effect of moving Key\/Value operations which were in the Bucket context for SDK 1.0 into the Collection context for SDK 2.0. Cross Bucket operations such as Search, Analytics and N1QL are now done at the Cluster level.<\/p>\n
Couchbase Server 6.5 will support Scopes and Collections as a part of “Developer Preview”, Developer Preview is not<\/em>\u00a0supported for use in production. In the meantime, SDK 2.0 also supports Couchbase 5.0 and higher by using the default Scope and Collection.<\/p>\n The focus on this alpha is to provide the API to use Couchbase Server with Key\/Value operations, N1QL, search, and analytics queries, as well as views. It contains the familiar Cluster and Bucket logical structures as well as the new Scope and Collections structures. Highlights can be grouped into two sections. The first is the new API which has been revamped across all SDKs to provide simpler, more future proof access patterns. The second is Go SDK specific enhancements.<\/p>\n The API has been significantly slimmed down and reworked so that the individual method calls are easier to find and more uniform. For Go this means we no longer need to have multiple calls for similar, but different, functions. We’ve also slimmed down the number of parameters required in some functions.<\/p>\n For example, in SDK 1.0 there were method signatures like:<\/p>\n In SDK 2.0 this has changed to:<\/p>\n Each method returns a *Result<\/span> and has an optional parameter called *Options<\/span>. Anything required for an operation to work is a parameter and optional properties (like the timeout, the durability requirements, the cas value etc…) have all been moved into options blocks. This has lead to fewer “overloaded” functions and a simpler overall API. Mutation type operation results contain things like CAS values and Mutation Token. For Fetch type operations the results contain ways to get your value and document expiration (if requested).<\/p>\n Options block are structs that look like:<\/p>\n This provides much more flexibility at an operation level than the previous API. This means that previously if you wanted to do an insert with persist to<\/span>\u00a0 set then you had to do InsertDura(“key”, “value”, 0, 0, 1)<\/span> , now it’s just Insert(“key”, “value”, &InsertOptions{PersistTo: 1})<\/span>\u00a0.<\/p>\n We now have support for context.Context<\/span> for cancellation. What this means is that you can use things like take the context from your HTTP handler and supply it straight into your gocb operation, so you have the same cancellation structure used throughout your HTTP request handler. If you don’t want to use Context<\/span> for timeouts then don’t worry, you can just use the Timeout<\/span>\u00a0 option instead.<\/p>\n The query APIs, much like the Key Value API, now use\u00a0*Options<\/span> blocks for optional query properties. Previously the APIs looked like:<\/p>\n It now looks like:<\/p>\n The options blocks for these are too big to include here but they look, and work, similar to the Key Value example above. We’ve also improved API consistency across the query services by updating how results are accessed. We’re still working on custom transcoding of these results. All of the services now also use streaming to retrieve the results under the hood, this means that you can query for huge datasets without having to worry about running out of memory.<\/p>\n Previously, we exposed sentinel errors (e.g. if err == gocb.ErrKeyNotFound<\/span> ) that you had to match against if your operation returned an error and you had specific error types that you needed to handle. We’ve changed this, we now expose errors as types and also provide helper functions for categorising errors. You can now do if gocb.IsKeyNotFound(err)<\/span>, or type assert the entire error kvErr := err.(gocb.KeyValueError)<\/span>\u00a0 and get access to underlying context about the error if you need that too.<\/p>\n You can start using all of these enhancements by doing: go get github.com\/couchbase\/gocb@v2.0.0-alpha.3<\/span><\/p>\n Once you have the SDK then you can connect to a cluster, open a bucket and use the default collection. For now, unless you use the Developer Preview mode in Couchbase Server 6.5 then you’ll only be able use the default collection.<\/p>\n Note that bucket open no longer returns an error, although this is still where connecting occurs. Instead, we defer returning errors until the first operation. In the future you will be able to check the health of the bucket connection before performing operations.<\/p>\n If you want to learn more, please take a look into our new\u00a0documentation<\/a>\u00a0which is starting to come together as well.<\/p>\n The API is pretty new, and alpha, so is still subject to change – although it shouldn’t change drastically. We’d really appreciate all feedback and bug reports to make this the best SDK we have ever delivered. This is your chance to help shape the future of the Couchbase Go SDK.<\/p>\nHighlights of the SDK 2.0 API<\/h2>\n
Key Value API Improvements<\/h3>\n
func (b *Bucket) Insert(key string, value interface{}, expiry uint32) (Cas, error)\r\nfunc (b *Bucket) InsertDura(key string, value interface{}, expiry uint32, replicateTo, persistTo uint) (Cas, error)\r\nfunc (b *Bucket) Get(key string, valuePtr interface{}) (Cas, error)\r\n<\/pre>\nfunc (c *Collection) Insert(key string, val interface{}, opts *InsertOptions) (*MutationResult, error)\r\nfunc (c *Collection) Get(key string, opts *GetOptions) (*GetResult, error)<\/pre>\ntype InsertOptions struct {\r\n\tParentSpanContext opentracing.SpanContext\r\n\tTimeout time.Duration\r\n\tContext context.Context\r\n\t\/\/ The expiration length in seconds\r\n\tExpiration uint32\r\n\tPersistTo uint\r\n\tReplicateTo uint\r\n\tDurabilityLevel DurabilityLevel\r\n\tEncoder Encode\r\n}<\/pre>\nQuery API Improvements<\/h3>\n
func (c *Cluster) ExecuteN1qlQuery(q *N1qlQuery, params interface{}) (QueryResults, error)\r\nfunc (c *Cluster) ExecuteAnalyticsQuery(q *AnalyticsQuery, params interface{}) (AnalyticsResults, error)\r\nfunc (c *Cluster) ExecuteSearchQuery(q *SearchQuery) (SearchResults, error)\r\nfunc (b *Bucket) ViewQuery(designDoc string, viewName string, opts *ViewOptions) (*ViewResults, error)<\/pre>\nfunc (c *Cluster) Query(statement string, opts *QueryOptions) (*QueryResults, error)\r\nfunc (c *Cluster) AnalyticsQuery(statement string, opts *AnalyticsQueryOptions) (*AnalyticsResults, error)\r\nfunc (c *Cluster) SearchQuery(q SearchQuery, opts *SearchQueryOptions) (*SearchResults, error)\r\nfunc (b *Bucket) ViewQuery(designDoc string, viewName string, opts *ViewOptions) (*ViewResults, error)<\/pre>\n
Error Handling Improvements<\/h3>\n
Getting Started<\/h2>\n
cluster, err := gocb.Connect(\"localhost\", gocb.ClusterOptions{Authenticator: gocb.PasswordAuthenticator{\r\n Username: \"username\",\r\n Password: \"password\",\r\n}})\r\nif err != nil {\r\n panic(\"error connecting to cluster:\" + err.Error())\r\n}\r\nbucket := cluster.Bucket(\"bucket-name\", nil)\r\ncollection := bucket.DefaultCollection(nil)\r\n\r\n\/\/ Now you can perform operations:\r\n\r\nupsertResult, err := collection.Upsert(\"somekey\", \"somevalue\", &gocb.UpsertOptions{Timeout: 10*time.Millisecond})\r\nif err != nil {\r\n panic(err)\r\n}\r\n\r\nfmt.Println(upsertResult.Cas())\r\n\r\ngetResult, err := collection.Get(\"somekey\", nil)\r\nif err != nil {\r\n panic(err)\r\n}\r\n\r\nvar myValue string\r\nerr = getResult.Content(&myValue)\r\nif err != nil {\r\n panic(err)\r\n}\r\n\r\nctx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond)\r\ndefer cancel()\r\nresults, err := cluster.Query(\"SELECT `bucket-name`.* from `bucket-name` LIMIT 10\", &gocb.QueryOptions{\r\n\tContext: ctx,\r\n})\r\nif err != nil {\r\n panic(err)\r\n}\r\nvar myQueryValue interface{}\r\nfor results.Next(&myQueryValue) {\r\n}\r\n\r\nerr = results.Close() \r\nif err != nil { \r\n panic(err) \r\n}\r\n<\/pre>\nHow do we version?<\/h2>\n