Configuration

SageConfig contains all connection settings. The same SageClient and commands work with a standalone server, a cluster, or a master-replica deployment. Only the configuration changes.

val config = SageConfig(
  topology = Topology.Standalone(Endpoint("localhost", 6379))
)

Every field has a sensible default, so SageConfig() connects to a local standalone server. The sections below cover the fields that shape connectivity; Connection tuning summarizes the operational knobs.

Standalone

The default topology. A single endpoint, and optionally a logical database:

val config = SageConfig(
  topology = Topology.Standalone(Endpoint("localhost", 6379)),
  database = 0
)

The database is selected at connection setup and fixed for the client's lifetime. There is no runtime SELECT, because it would move the keyspace under every fiber sharing the connection.

Cluster

Give the cluster seeds. Sage discovers the full topology from them, routes each command to the node owning its key's slot, and follows MOVED/ASK redirects transparently:

val config = SageConfig(
  topology = Topology.Cluster(
    Vector(Endpoint("localhost", 7000), Endpoint("localhost", 7001))
  ),
  database = 0
)

Seeds bootstrap discovery only. Once the topology is known, Sage routes to the nodes the cluster reports; any one seed answering is enough.

A non-zero database in cluster mode needs Valkey 9+ with a large enough cluster-databases setting. Redis Cluster and older Valkey versions reject the connection.

Hash tags

Redis Cluster hashes the bytes inside the first non-empty {...} pair instead of the whole key. Use the same tag in every key that must live in one slot, for example user:{42}:profile and user:{42}:settings. Transactions require all keys to share one slot.

Supported cross-slot commands

mGet, mSet, exists, del, unlink, and touch may span slots. Sage groups their keys by slot, sends one subcommand per slot, and merges the replies back into one: mGet restores request order (keeping missing and repeated positions), exists, del, unlink, and touch sum their counts, and mSet succeeds only if every group returns OK. This works inside a pipeline too.

Each slot's subcommand is atomic on its own, but the call as a whole is not. A cross-slot mGet is not a point-in-time snapshot, and a failing mSet, del, or unlink may already have written to the groups that succeeded. If any group fails, the whole call fails. Use a common hash tag when the operation must be atomic.

mSetNx is never split, since that would break its all-or-nothing condition, and no cross-slot command is allowed inside a transaction, which must stay pinned to one slot.

Commands that run on every master

Each node sees only part of the keyspace. Script and function caches are also local to a node, as is pub/sub subscription information. For this reason, scriptLoad, scriptExists, scriptFlush, the function* mutations, flushAll, flushDb, keys, dbSize, waitReplicas, waitAof, memoryPurge, and the pubsub* introspection forms run on every slot-owning master, and their replies are folded into one: keys returns the whole keyspace, dbSize the cluster total, pubsubChannels every active channel, pubsubNumSub the summed subscriber count. If any master fails, the whole call fails.

None of them can go in a pipeline, which batches per node — run them on the client directly; dbSize is also rejected inside a transaction, which pins to one node. Only masters are visited, so a subscriber connected through a replica is not counted by pubsubNumSub, and pubsubNumPat counts a pattern once per master holding it.

The keyless administrative commands — info, configGet, configSet, slowLog*, latency*, commandLog*, functionDump — are answered by a single master instead. Note that configSet sets the parameter on one master, not across the cluster. A keyless read such as randomKey is also answered by one node, but follows the read routing policy, so it can be served by a replica.

This is also the one case where Sage does not retry a -CLUSTERDOWN for you; see Refusals Sage retries for you.

Topology refresh

Sage re-reads the slot map whenever a command shows it is out of date: a MOVED or ASK redirect, a slot no known node covers, a node that is unreachable or no longer a master. Reshardings and failovers therefore need no configuration.

Adding a replica does not produce a redirect or connection failure, so Sage has no reason to refresh the topology. Reads under ReadFrom.Replica or ReadFrom.ReplicaPreferred continue using the replicas already known. Set topologyRefreshInterval to check for new replicas on a timer:

val config = SageConfig(
  topology = Topology.Cluster(
    Vector(Endpoint("localhost", 7000)),
    ClusterConfig(topologyRefreshInterval = Some(30.seconds))
  ),
  readFrom = ReadFrom.Replica
)

Sage refreshes on a timer only when you configure this setting. Each refresh costs one CLUSTER SLOTS, and ticks arriving within minRefreshInterval of the last refresh are skipped, so a short interval cannot flood the cluster. MasterReplicaConfig has the same setting.

Master-replica

Select Topology.MasterReplica with seed endpoints. Sage discovers the nodes' roles, sends writes to the master, and routes reads per the read policy:

val config = SageConfig(
  topology = Topology.MasterReplica(
    Vector(Endpoint("localhost", 6379), Endpoint("localhost", 6380))
  ),
  readFrom = ReadFrom.ReplicaPreferred
)

The number of endpoints decides where Sage may connect:

Seeds	Nodes Sage dials
Several	only the supplied endpoints, each classified by its own ROLE. Addresses that ROLE advertises are ignored, and a replica is used once it reports connected
One	the supplied endpoint and the master or replicas discovered from its ROLE reply

Use several endpoints for managed deployments whose stable primary and reader names differ from the per-node addresses Redis advertises.

An endpoint that is unreachable, or a replica that is still synchronizing, is left out at connect time so a partially available deployment still connects. Sage adds it again when a command shows that the topology has changed, without polling. However, adding a second replica does not produce such a signal. Set topologyRefreshInterval if you scale readers out; see Topology refresh.

Read routing

readFrom controls which node may run a read-only command. The same setting applies to cluster and master-replica deployments:

ReadFrom	Reads go to
Master (default)	the master, always
MasterPreferred	the master, falling back to a replica
Replica	a replica, failing if none is reachable
ReplicaPreferred	a replica, falling back to the master

Only read-only commands can use this setting. Writes, and any command not marked read-only, always go to the master. A replica may return older data than the master. This is an expected trade-off when reading from replicas.

TLS and ACL

Both are configured on the same client. tls selects the trust source, and auth sets the ACL username and password:

val config = SageConfig(
  topology = Topology.Standalone(Endpoint("localhost", 6380)),
  tls = Some(TlsConfig(TrustSource.System)),
  auth = Some(AuthConfig(username = "app", password = "app-secret"))
)

TrustSource.System uses the system trust store. Use TrustSource.Pem or TrustSource.TrustStore for a private CA. Use TrustSource.Custom(sslContext) to supply your own SSLContext, including for mutual TLS. AuthConfig redacts its password in logs and in any printed SageConfig.

WARNING

TrustSource.Insecure is for local development only. It trusts every certificate and skips hostname verification, leaving the connection open to machine-in-the-middle attacks. Never use it in production.

Connection tuning

The remaining fields tune connection lifecycle, pooling, and observability. Each is its own config type with its own defaults, so you set only what you need:

Field	Tunes	Defaults
connectTimeout	each socket connect, TLS handshake, and connection-setup command	10.seconds
reconnect (BackoffConfig)	exponential reconnect backoff with full jitter	50.millis to 5.seconds, ×2
watchdog (WatchdogConfig)	connection liveness checks for pending commands and idle connections	ping every 60.seconds, 30.seconds timeout
closeTimeout	how long close waits for in-flight commands to finish (blocking commands and transactions are closed at once)	5.seconds
dedicatedPool (DedicatedPoolConfig)	the pool behind blocking commands and transactions, per node	max 8, acquire 5.seconds, idle 30.seconds
pubsub (PubSubConfig)	per-subscription message buffer size	128
clientCache (CacheConfig)	client-side caching on/off and size cap	enabled, 64 MB
clientName	CLIENT SETNAME, shown in CLIENT LIST / CLIENT INFO	none
listeners	observers of runtime events (SageListener)	none
tracer	distributed-tracing spans on the command path (CommandTracer)	none

dedicatedPool.maxConnections is a ceiling per node, not per client: a blocking command runs on the node holding its keys, so every node gets its own pool. Connections open on demand and idle ones are evicted, so the ceiling is what a burst can reach, but size it against maxclients with your node count in mind.

For example, a cluster client with a shorter connect timeout, a larger blocking-command pool, a more frequent watchdog, and a name:

import scala.concurrent.duration.*

val config = SageConfig(
  topology = Topology.Cluster(Vector(Endpoint("localhost", 7000))),
  connectTimeout = 5.seconds,
  dedicatedPool = DedicatedPoolConfig(maxConnections = 16),
  watchdog = WatchdogConfig(pingInterval = 30.seconds),
  clientName = Some("orders-service")
)

Disable client-side caching where the server permits ordinary commands but denies CLIENT TRACKING (some proxies and ACL setups); cached reads then run without caching, keeping the call portable:

val config = SageConfig(
  topology = Topology.Standalone(Endpoint("localhost", 6379)),
  clientCache = CacheConfig(enabled = false)
)

From a connection URI

For the common cases you can parse a redis:// or rediss:// URI instead of assembling the config by hand. rediss selects TLS with system trust, userinfo becomes the ACL auth, a /<db> path sets the database, and comma-separated hosts yield cluster seeds. It returns the problem as a Left rather than throwing, and there is intentionally no way to select insecure TLS from a URI:

// fromUri returns Either: a Left describes the problem, a Right is the config
val parsed = SageConfig.fromUri("rediss://app:app-secret@localhost:6380/0")
// Further tuning stays programmatic:
//   SageConfig.fromUri(uri).map(_.copy(readFrom = ReadFrom.ReplicaPreferred))