Client Initialization
Valkey GLIDE provides support for both Cluster and Standalone configurations. Please refer to the relevant section based on your specific setup.
Cluster
Section titled “Cluster”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.
Connecting to a Cluster
Section titled “Connecting to a Cluster”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();from glide import ( GlideClusterClient, GlideClusterClientConfiguration, NodeAddress)
addresses = [NodeAddress(host="address.example.com", port=6379)]client_config = GlideClusterClientConfiguration(addresses)
client = await GlideClusterClient.create(client_config)import {GlideClusterClient} from "@valkey/valkey-glide";
const addresses = [ { host: "address.example.com", port: 6379 }];
const client = await GlideClusterClient.createClient({ addresses: addresses});import ( glide "github.com/valkey-io/valkey-glide/go/v2" "github.com/valkey-io/valkey-glide/go/v2/config")
func ConnectCluster() { myConfig := config.NewClusterClientConfiguration(). WithAddress(&config.NodeAddress{Host: "address.example.com", Port: 6379})
client, err := glide.NewClusterClient(myConfig)}try { $addresses = [ ['host' => 'address.example.com', 'port' => 6379] ];
$client = new ValkeyGlideCluster(addresses: $addresses);} catch (ValkeyGlideException $e) { error_log("Failed to connect to cluster: " . $e->getMessage());}using Valkey.Glide;using static Valkey.Glide.ConnectionConfiguration;
var config = new ClusterClientConfigurationBuilder() .WithAddress("address.example.com", 6379) .Build();
await using var client = await GlideClusterClient.CreateClient(config);require "valkey"
client = Valkey.new( nodes: [{ host: "address.example.com", port: 6379 }], cluster_mode: true)Request Routing
Section titled “Request Routing”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.
Please refer to the documentation within the code.
Please refer to the documentation within the code.
Please refer to the documentation within the code for routing configuration.
Please refer to the documentation within the code for routing configuration.
Please refer to the documentation within the code for routing configuration.
Please refer to the documentation within the code for routing configuration.
Response Aggregation
Section titled “Response Aggregation”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:
Please refer to the documentation within the code.
Please refer to the documentation within the code.
Please refer to the documentation within the code.
Please refer to the documentation within the code.
Please refer to the documentation within the code for command return types.
Please refer to the documentation within the code for cluster response types.
Please refer to the documentation within the code.
Topology Updates
Section titled “Topology Updates”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.
Standalone
Section titled “Standalone”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.
Connecting to a Standalone Server
Section titled “Connecting to a Standalone Server”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();from glide import ( GlideClient, GlideClientConfiguration, NodeAddress)
addresses = [ NodeAddress(host="primary.example.com", port=6379), NodeAddress(host="replica1.example.com", port=6379), NodeAddress(host="replica2.example.com", port=6379) ]client_config = GlideClientConfiguration(addresses)
client = await GlideClient.create(client_config)import {GlideClient} from "@valkey/valkey-glide";
const addresses = [ { host: "primary.example.com", port: 6379 }, { host: "replica1.example.com", port: 6379 }, { host: "replica2.example.com", port: 6379 },];
const client = await GlideClient.createClient({ addresses: addresses});import ( glide "github.com/valkey-io/valkey-glide/go/v2" "github.com/valkey-io/valkey-glide/go/v2/config")
func ConnectStandalone() { myConfig := config.NewClientConfiguration(). WithAddress(&config.NodeAddress{Host: "primary.example.com", Port: 6379}). WithAddress(&config.NodeAddress{Host: "replica1.example.com", Port: 6379}). WithAddress(&config.NodeAddress{Host: "replica2.example.com", Port: 6379})
client, err := glide.NewClient(myConfig)}try { $addresses = [ ['host' => 'primary.example.com', 'port' => 6379], ['host' => 'replica1.example.com', 'port' => 6379], ['host' => 'replica2.example.com', 'port' => 6379] ];
$client = new ValkeyGlide(); $client->connect(addresses: $addresses);} catch (ValkeyGlideException $e) { error_log("Failed to connect to standalone server: " . $e->getMessage());}using Valkey.Glide;using static Valkey.Glide.ConnectionConfiguration;
var config = new StandaloneClientConfigurationBuilder() .WithAddress("primary.example.com", 6379) .WithAddress("replica1.example.com", 6379) .WithAddress("replica2.example.com", 6379) .Build();
await using var client = await GlideClient.CreateClient(config);require "valkey"
# The Ruby client connects to a single standalone address.# Use the read_from option to route reads to replicas.client = Valkey.new(host: "primary.example.com", port: 6379)
# Or connect with a URLclient = Valkey.new(url: "redis://primary.example.com:6379/0")Connect through a Unix domain socket
Section titled “Connect through a Unix domain socket”Unix domain socket connections are currently available only in the Python standalone client.
from glide import GlideClient, GlideClientConfiguration, NodeAddress
config = GlideClientConfiguration( addresses=[NodeAddress(unix_socket_path="/run/valkey/valkey.sock")],)client = await GlideClient.create(config)The synchronous client accepts the same GlideClientConfiguration.
Unix domain socket limitations
Section titled “Unix domain socket limitations”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_ALLnode 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.
Configure node discovery
Section titled “Configure node discovery”For standalone clients, the node discovery mode controls how the client identifies the primary and replicas:
STANDARDis the default. It verifies node roles withINFO REPLICATIONand uses only the addresses you provide.STATICtrusts 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 supportINFO.DISCOVER_ALLdiscovers the primary and all replicas from any starting node. Discovery runs once, at client creation.DISCOVER_ALLcannot 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();from glide import ( GlideClient, GlideClientConfiguration, NodeAddress, NodeDiscoveryMode,)
config = GlideClientConfiguration( addresses=[NodeAddress(host="proxy.example.com", port=6379)], node_discovery_mode=NodeDiscoveryMode.STATIC,)client = await GlideClient.create(config)import { GlideClient, NodeDiscoveryMode } from "@valkey/valkey-glide";
const client = await GlideClient.createClient({ addresses: [{ host: "proxy.example.com", port: 6379 }], nodeDiscoveryMode: NodeDiscoveryMode.Static,});import ( glide "github.com/valkey-io/valkey-glide/go/v2" "github.com/valkey-io/valkey-glide/go/v2/config")
clientConfig := config.NewClientConfiguration(). WithAddress(&config.NodeAddress{Host: "proxy.example.com", Port: 6379}). WithNodeDiscoveryMode(config.NodeDiscoveryModeStatic)
client, err := glide.NewClient(clientConfig)$client = new ValkeyGlide();$client->connect( addresses: [['host' => 'proxy.example.com', 'port' => 6379]], node_discovery_mode: ValkeyGlide::NODE_DISCOVERY_MODE_STATIC);using Valkey.Glide;using static Valkey.Glide.ConnectionConfiguration;
var config = new StandaloneClientConfigurationBuilder() .WithAddress("proxy.example.com", 6379) .WithNodeDiscoveryMode(NodeDiscoveryMode.Static) .Build();
await using var client = await GlideClient.CreateClient(config);Configuration Options
Section titled “Configuration Options”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.