Go Client SDK

Installing Go client SDK


go get github.com/oxia-db/oxia/oxia

GoDoc documenation is available at https://pkg.go.dev/github.com/oxia-db/oxia/oxia

Sync and Async APIs

Oxia provides two API flavors in the client:

Sync: Easier and convenient to use
Async: Returns channels to track completion of the operations. Allows to have more operations outstanding and achieve higher throughput

All the features are available in either API.

Client API

Initializing the client

To use the Oxia client, you need to create a client instance. Once created, a client instance will be valid until it’s explicitly closed, and it can be used from different go-routines.

Sync


client, err := oxia.NewSyncClient("localhost:6648")

When creating the client is possible to pass several options, such as:


client, err := oxia.NewSyncClient("localhost:6648",
        oxia.WithNamespace("my-namespace"),
        oxia.WithBatchLinger(10*time.Milliseconds)),
        )

Available client options include:

Option	Description	Default
`WithNamespace(namespace string)`	Set the Oxia namespace to use	`"default"`
`WithBatchLinger(duration time.Duration)`	How long to wait before sending a batched request	`5ms`
`WithMaxRequestsPerBatch(count int)`	Maximum number of requests in a batch	`1000`
`WithRequestTimeout(duration time.Duration)`	How long to wait for responses before cancelling	`30s`
`WithSessionTimeout(duration time.Duration)`	Session timeout for ephemeral records	`15s`
`WithMeterProvider(provider metric.MeterProvider)`	Custom OpenTelemetry meter provider	`noop.NewMeterProvider()`
`WithGlobalMeterProvider()`	Use the global OpenTelemetry meter provider	-
`WithIdentity(identity string)`	Set a custom client identity	Random UUID
`WithTLS(config *tls.Config)`	Configure TLS for secure connections	`nil`
`WithAuthentication(auth auth.Authentication)`	Configure authentication	`nil`

Writing records

Sync


// Write a record to Oxia with the specified key and value, and with the expectation
// that the record does not already exist.
insertedKey1, res1, err := client.Put(context.Background(), "/my-key", []byte("value-1"), ExpectedRecordNotExists())
 
// Write a record with the expectation that it has not changed since the previous write.
// If there was any change, the operation will fail
insertedKey2, res2, err := client.Put(context.Background(), "/my-key", []byte("value-2"), ExpectedVersionId(res1.VersionId))

Reading records

Reading the value of a record

Sync


key, value, version, err := client.Get(context.Background(), "/my-key")

Available options for get operation:

Option	Description	Default
`ComparisonEqual()`	Sets the Get() operation to compare the stored key for equality	Yes
`ComparisonFloor()`	Search for the record whose key is the highest key < = to the supplied key
`ComparisonCeiling()`	Search for the record whose key is the lowest key >= to the supplied key.
`ComparisonLower()`	Search for the record whose key is strictly < to the supplied key.
`ComparisonHigher()`	Search for the record whose key is strictly > to the supplied key.
`IncludeValue(include bool)`	Whether to include the value in the response, or just the version id	`true`
`UseIndex(indexName string)`	Specify a different secondar index to search for the key
`PartitionKey(partitionKey string)`	Overrides the partition routing with the specified `partitionKey` instead of the regular record key.