Skip to content

Client Initialization

Valkey GLIDE provides support for both Cluster and Standalone configurations. Please refer to the relevant section based on your specific setup.

Valkey GLIDE supports Cluster deployments, where the database is partitioned across multiple primary shards, with each shard being represented by a primary node and zero or more replica nodes.

To initialize a cluster client, you need to provide a configuration that includes the addresses of initial seed nodes. Valkey GLIDE automatically discovers the entire cluster topology, eliminating the necessity of explicitly listing all cluster nodes.

The NodeAddress type represents the host and port of a cluster node. The host can be either an IP address, a hostname, or a fully qualified domain name (FQDN).

import glide.api.GlideClusterClient;
import glide.api.models.configuration.GlideClusterClientConfiguration;
import glide.api.models.configuration.NodeAddress;
NodeAddress address = NodeAddress.builder()
.host("address.example.com")
.port(6379)
.build();
GlideClusterClientConfiguration config = GlideClusterClientConfiguration.builder()
.address(address)
.build();
GlideClusterClient clusterClient = GlideClusterClient.createClient(config).get();

In the cluster, data is divided into slots, and each primary node within the cluster is responsible for specific slots. Valkey GLIDE adheres to Valkey OSS guidelines when determining the node(s) to which a command should be sent in clustering mode.

For more details on the routing of specific commands:

Please refer to the documentation within the code for routing configuration.

When requests are dispatched to multiple shards in a cluster (as discussed in the Request Routing section), the client needs to aggregate the responses for a given command. Valkey GLIDE follows Valkey OSS guidelines for determining how to aggregate the responses from multiple shards within a cluster.

To learn more about response aggregation for specific commands:

The cluster’s topology can change over time. New nodes can be added or removed, and the primary node owning a specific slot may change. Valkey GLIDE is designed to automatically rediscover the topology whenever the server indicates a change in slot ownership. This ensures that the Valkey GLIDE client stays in sync with the cluster’s topology.

Valkey GLIDE also supports Standalone deployments, where the database is hosted on a single primary node, optionally with replica nodes. To initialize a standalone client, you should create a configuration that includes the addresses of primary and all replica nodes.

import glide.api.GlideClient;
import glide.api.models.configuration.GlideClientConfiguration;
import glide.api.models.configuration.NodeAddress;
GlideClientConfiguration config = GlideClientConfiguration.builder()
.address(NodeAddress.builder()
.host("primary.example.com")
.port(6379)
.build())
.address(NodeAddress.builder()
.host("replica1.example.com")
.port(6379)
.build())
.address(NodeAddress.builder()
.host("replica2.example.com")
.port(6379)
.build())
.build();
GlideClient standaloneClient = GlideClient.createClient(config).get();

Unix domain socket connections are currently available only in the Python standalone client.

GLIDE rejects the client configuration at creation time if a Unix domain socket address:

  • Uses a relative path. The path must be absolute, for example /run/valkey/valkey.sock, and short enough to fit in a socket address.
  • Also sets a host or port.
  • Is mixed with TCP addresses in the same configuration.
  • Is used with TLS.
  • Is used with the DISCOVER_ALL node discovery mode.
  • Is used with a cluster client. Unix domain sockets are supported only for standalone clients.
  • Is used on Windows. Unix domain sockets are supported only on Unix platforms.

For standalone clients, the node discovery mode controls how the client identifies the primary and replicas:

  • STANDARD is the default. It verifies node roles with INFO REPLICATION and uses only the addresses you provide.
  • STATIC trusts the provided addresses without checking their roles. The first address is treated as the primary. Use this mode when connecting through a proxy such as Envoy or HAProxy that does not support INFO.
  • DISCOVER_ALL discovers the primary and all replicas from any starting node. Discovery runs once, at client creation. DISCOVER_ALL cannot be combined with read-only mode or Unix domain socket addresses.

When using STATIC mode through a proxy, do not configure a client name because the proxy might not support CLIENT SETNAME. The examples below configure STATIC mode; use the corresponding DISCOVER_ALL value with any primary or replica address to discover the complete standalone topology.

import glide.api.GlideClient;
import glide.api.models.configuration.GlideClientConfiguration;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.NodeDiscoveryMode;
GlideClientConfiguration config = GlideClientConfiguration.builder()
.address(NodeAddress.builder()
.host("proxy.example.com")
.port(6379)
.build())
.nodeDiscoveryMode(NodeDiscoveryMode.STATIC)
.build();
GlideClient client = GlideClient.createClient(config).get();

GLIDE clients uses configuration objects to configure connections to Valkey. This keeps a consistent interface between clients while staying within the idiomatic norms of each specific programming language.

Refer to our Connection Options page for more on the available options for each client.