github.com/hazelcast/hazelcast-go-client
Package hazelcast provides the Hazelcast Go client. Hazelcast is an open-source distributed in-memory data store and computation platform. It provides a wide variety of distributed data structures and concurrency primitives. Hazelcast Go client is a way to communicate to Hazelcast IMDG clusters and access the cluster data. If you are using Hazelcast and Go Client on the same computer, generally the default configuration should be fine. This is great for trying out the client. However, if you run the client on a different computer than any of the cluster members, you may need to do some simple configurations such as specifying the member addresses. The Hazelcast members and clients have their own configuration options. You may need to reflect some of the member side configurations on the client side to properly connect to the cluster. In order to configure the client, you only need to create a new `hazelcast.Config{}`, which you can pass to `hazelcast.StartNewClientWithConnfig` function: Calling hazelcast.StartNewClientWithConfig with the default configuration is equivalent to hazelcast.StartNewClient. The default configuration assumes Hazelcast is running at localhost:5701 with the cluster name set to dev. If you run Hazelcast members in a different server than the client, you need to make certain changes to client settings. Assuming Hazelcast members are running at hz1.server.com:5701, hz2.server.com:5701 and hz3.server.com:5701 with cluster name production, you would use the configuration below. Note that addresses must include port numbers: You can also load configuration from JSON: If you are changing several options in a configuration section, you may have to repeatedly specify the configuration section: You can simplify the code above by getting a reference to config.Cluster and update it: Note that you should get a reference to the configuration section you are updating, otherwise you would update a copy of it, which doesn't modify the configuration. There are a few options that require a duration, such as config.Cluster.HeartbeatInterval, config.Cluster.Network.ConnectionTimeout and others. You must use types.Duration instead of time.Duration with those options, since types.Duration values support human readable durations when deserialized from text: That corresponds to the following JSON configuration. Refer to https://golang.org/pkg/time/#ParseDuration for the available duration strings: Here are all configuration items with their default values: Checkout the nearcache package for the documentation about the Near Cache. You can listen to creation and destroy events for distributed objects by attaching a listener to the client. A distributed object is created when first referenced unless it already exists. Here is an example: If you don't want to receive any distributed object events, use client.RemoveDistributedObjectListener: Running SQL queries require Hazelcast 5.0 and up. Check out the Hazelcast SQL documentation here: https://docs.hazelcast.com/hazelcast/latest/sql/sql-overview The SQL support should be enabled in Hazelcast server configuration: The client supports two kinds of queries: The ones returning rows (select statements and a few others) and the rest (insert, update, etc.). The former kinds of queries are executed with QuerySQL method and the latter ones are executed with ExecSQL method. Use the question mark (?) for placeholders. To connect to a data source and query it as if it is a table, a mapping should be created. Currently, mappings for Map, Kafka and file data sources are supported. You can read the details about mappings here: https://docs.hazelcast.com/hazelcast/latest/sql/sql-overview#mappings The following data types are supported when inserting/updating. The names in parantheses correspond to SQL types: Using Date/Time In order to force using a specific date/time type, create a time.Time value and cast it to the target type: Hazelcast Management Center can monitor your clients if client-side statistics are enabled. You can enable statistics by setting config.Stats.Enabled to true. Optionally, the period of statistics collection can be set using config.Stats.Period setting. The labels set in configuration appear in the Management Center console:
Readme
Hazelcast is an open-source distributed in-memory data store and computation platform that provides a wide variety of distributed data structures and concurrency primitives.
Hazelcast Go client is a way to communicate with Hazelcast 4 and 5 clusters and access the cluster data.
package main
import (
"context"
"fmt"
"log"
"github.com/hazelcast/hazelcast-go-client"
)
func main() {
ctx := context.TODO()
// create the client and connect to the cluster on localhost
client, err := hazelcast.StartNewClient(ctx)
if err != nil {
log.Fatal(err)
}
// get a map
people, err := client.GetMap(ctx, "people")
if err != nil {
log.Fatal(err)
}
personName := "Jane Doe"
// set a value in the map
if err = people.Set(ctx, personName, 30); err != nil {
log.Fatal(err)
}
// get a value from the map
age, err := people.Get(ctx, personName)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s is %d years old.\n", personName, age)
// stop the client to release resources
client.Shutdown(ctx)
}
Requirements:
In your Go module enabled project, add a dependency to github.com/hazelcast/hazelcast-go-client:
# Depend on the latest release
$ go get github.com/hazelcast/hazelcast-go-client@latest
Hazelcast Go client requires a working Hazelcast cluster.
Check out our Get Started page for options.
Start the client with the default Hazelcast host and port using hazelcast.StartNewClient, when Hazelcast is running on local with the default options:
ctx := context.TODO()
client, err := hazelcast.StartNewClient(ctx)
// handle client start error
Note that Config structs are not thread-safe. Complete creation of the configuration in a single goroutine.
// create the default configuration
config := hazelcast.Config{}
// optionally set member addresses manually
config.Cluster.Network.SetAddresses("member1.example.com:5701", "member2.example.com:5701")
// create and start the client with the configuration provider
client, err := hazelcast.StartNewClientWithConfig(ctx, config)
// handle client start error
Hazelcast Go Client documentation is hosted at pkg.go.dev.
You can view the documentation locally by using godoc:
$ godoc -http=localhost:5500
godoc is not installed by default with the base Go distribution. Install it using:
$ go get -u golang.org/x/tools/...`
Join us at Go Client channel or Hazelcast at Google Groups.
Currently, we support only Linux, MacOS and WSL (Windows Subsystem for Linux) for testing the client.
You need to have the following installed in order to run integration tests:
Before running the tests, starts Hazelcast Remote Controller, which enables the test suite to create clusters:
# Start RC with Hazelcast Community features
$ ./rc.sh start
# Or, start RC with Hazelcast Enterprise features
$ HAZELCAST_ENTERPRISE_KEY=ENTERPRISE-KEY-HERE ./rc.sh start
You can run the tests using one of the following approaches:
make test-all to run integration tests.make test-all-race to run integration tests with race detection.make test-cover to generate the coverage report and make view-cover to view the test coverage summary and generate an HTML report.Testing the client with SSL support requires running the remote controller with Hazelcast Enterprise features.
To enable SSL connections, add ENABLE_SSL=1 to environment variables, or prepend it to the make commands above.
In order to turn on verbose logging, add ENABLE_TRACE=1 to environment variables, or prepend it to the make commands above.
Copyright (c) 2008-2021, Hazelcast, Inc. All Rights Reserved.
Visit www.hazelcast.com for more information.
FAQs
Package hazelcast provides the Hazelcast Go client. Hazelcast is an open-source distributed in-memory data store and computation platform. It provides a wide variety of distributed data structures and concurrency primitives. Hazelcast Go client is a way to communicate to Hazelcast IMDG clusters and access the cluster data. If you are using Hazelcast and Go Client on the same computer, generally the default configuration should be fine. This is great for trying out the client. However, if you run the client on a different computer than any of the cluster members, you may need to do some simple configurations such as specifying the member addresses. The Hazelcast members and clients have their own configuration options. You may need to reflect some of the member side configurations on the client side to properly connect to the cluster. In order to configure the client, you only need to create a new `hazelcast.Config{}`, which you can pass to `hazelcast.StartNewClientWithConnfig` function: Calling hazelcast.StartNewClientWithConfig with the default configuration is equivalent to hazelcast.StartNewClient. The default configuration assumes Hazelcast is running at localhost:5701 with the cluster name set to dev. If you run Hazelcast members in a different server than the client, you need to make certain changes to client settings. Assuming Hazelcast members are running at hz1.server.com:5701, hz2.server.com:5701 and hz3.server.com:5701 with cluster name production, you would use the configuration below. Note that addresses must include port numbers: You can also load configuration from JSON: If you are changing several options in a configuration section, you may have to repeatedly specify the configuration section: You can simplify the code above by getting a reference to config.Cluster and update it: Note that you should get a reference to the configuration section you are updating, otherwise you would update a copy of it, which doesn't modify the configuration. There are a few options that require a duration, such as config.Cluster.HeartbeatInterval, config.Cluster.Network.ConnectionTimeout and others. You must use types.Duration instead of time.Duration with those options, since types.Duration values support human readable durations when deserialized from text: That corresponds to the following JSON configuration. Refer to https://golang.org/pkg/time/#ParseDuration for the available duration strings: Here are all configuration items with their default values: Checkout the nearcache package for the documentation about the Near Cache. You can listen to creation and destroy events for distributed objects by attaching a listener to the client. A distributed object is created when first referenced unless it already exists. Here is an example: If you don't want to receive any distributed object events, use client.RemoveDistributedObjectListener: Running SQL queries require Hazelcast 5.0 and up. Check out the Hazelcast SQL documentation here: https://docs.hazelcast.com/hazelcast/latest/sql/sql-overview The SQL support should be enabled in Hazelcast server configuration: The client supports two kinds of queries: The ones returning rows (select statements and a few others) and the rest (insert, update, etc.). The former kinds of queries are executed with QuerySQL method and the latter ones are executed with ExecSQL method. Use the question mark (?) for placeholders. To connect to a data source and query it as if it is a table, a mapping should be created. Currently, mappings for Map, Kafka and file data sources are supported. You can read the details about mappings here: https://docs.hazelcast.com/hazelcast/latest/sql/sql-overview#mappings The following data types are supported when inserting/updating. The names in parantheses correspond to SQL types: Using Date/Time In order to force using a specific date/time type, create a time.Time value and cast it to the target type: Hazelcast Management Center can monitor your clients if client-side statistics are enabled. You can enable statistics by setting config.Stats.Enabled to true. Optionally, the period of statistics collection can be set using config.Stats.Period setting. The labels set in configuration appear in the Management Center console:
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A hospital in Mobile, Alabama, agreed to a settlement in a landmark ransomware death lawsuit, but is now reportedly reconsidering the agreement and refusing to pay.
Security News
A new report explores how advancements in LLMs are enhancing cyber threats, including polymorphic malware, personalized spearphishing, and the risk of hijacking customer service bots.
Security News
ESLint has approved an RFC that adds support for TypeScript configuration files, which is aimed at improving the developer experience and recognizing changes in the evolving JavaScript ecosystem.