Clarify Intended Use of NewFailoverClusterClient in Docs

[gopichanditv]

Hi Go Redis maintainers,

I am using NewFailoverClusterClient in a setup with:

Redis in non-cluster mode
1 master and 2 slaves
Sentinels monitoring the master

In practice, this works really well with RouteRandomly: true — reads are distributed randomly across replicas and the master, and writes correctly route to the current master even after a failover.

However, despite its name including "Cluster," there's no explicit documentation confirming or rejecting NewFailoverClusterClient's suitability for non-cluster, Sentinel-based Redis setups. This creates some ambiguity for developers.

Suggestion:

Please clarify in the documentation (function comment or README) whether NewFailoverClusterClient is officially supported for non-cluster, Sentinel-based Redis setups.

If it's not recommended, consider mentioning the risks or potential incompatibilities.

This would greatly help many developers understand when and how to use this function correctly, especially since using it in non-cluster mode with Sentinel appears to work reliably in many scenarios.

Thanks for your great work on this library!

[ndyakov]

Hello @gopichanditv, thank you for the suggestion. We will look into improving the README and the code documentation regarding the different types of clients.

[ndyakov]

@htemelski would you like to take a look at updating the docs.

[gopichanditv]

Hi @ndyakov / @htemelski ,

Just wanted to gently follow up on this — really appreciate you acknowledging the clarification required and planning to update the documentation!

In the meantime, I was hoping you could share a quick confirmation here: is it generally okay to use NewFailoverClusterClient with RouteRandomly: true in a Sentinel-based, non-cluster setup (1 master + 2 replicas)?

It's been working well while testing — reads are balanced, and fail over scenario also worked correctly — but I’d love to know if this usage is considered safe or officially supported, or if there are any gotchas we should be mindful of.

Thanks again for your time and for all the great work on go-redis!

[htemelski]

Hello @gopichanditv,
Generally Redis Sentinel and the sentinel client should support the topology you are using, and if you are saying that everything works and the load is balanced between the nodes it should be ok. Nevertheless I’ll look into the implementation to check id there are some caveats or if it’s just bad naming.

[htemelski-redis]

So I've looked into the implementations.
Currently, two different clients can be used, NewFailoverClusterClient and NewFailoverClient.
The difference is that the NewFailoverClient does not support RouteByLatency and RouteRandomly. If you don't need them, I would recommend using it, instead of the NewFailoverClusterClient, since there could be some overhead with the latter because it uses the ClusterClient, which calculates hash slots before executing a command.

Also please note that although a single sentinel can monitor multiple masters and their replicas, it's not able to monitor Redis setups in cluster mode.

[gopichanditv]

@htemelski-redis, Thanks a lot for looking into the implementations and for the detailed explanation — really appreciate it!

As a quick follow-up: since you’ve reviewed the internals, I wanted to confirm one thing.

In a Sentinel-based, non-cluster setup, where I’m using NewFailoverClusterClient with RouteRandomly: true — will the client continue to correctly handle master/slave role changes after a Sentinel-triggered failover?

Also, given that I’m not using a Redis cluster, can I safely assume that the internal hash slot calculations won’t break or interfere with command routing post-failover?

Thanks again for your time and for helping clarify these nuances!

[htemelski-redis]

For the first question
Yes, the failover sentinel client which is used by the cluster client listens for +switch-master event and should handle the master/slave role change. I will be able to run some tests later today/tomorrow just to verify that the logic works.

And yes, the internal slot calculation logic won't brake. I assume that the ClusterClient was reused out of convenience but all nodes are configured to handle all slots

slots := []ClusterSlot{
    {
        Start: 0,
	End:   16383,
	Nodes: nodes,
    },
}

[ndyakov]

@htemelski-redis should we add a note about the difference between the clients in the README and close this issue?

[htemelski-redis]

@gopichanditv Sorry for the delay,
I can confirm that the NewFailoverClusterClient will properly handle master/slave role changes.
Here's an example setup, stopping/restarting the master will properly trigger failover and one of the slaves will be promoted.

docker-compose.yaml

services:
  redis-master:
    image: redis:latest
    command: ['redis-server', '--appendonly', 'yes', '--protected-mode', 'no']

  redis-slave-1:
    image: redis:latest
    depends_on:
      - redis-master
    command:
      [
        'redis-server',
        '--replicaof',
        'redis-master',
        '6379',
        '--protected-mode',
        'no',
      ]

  redis-slave-2:
    image: redis:latest
    depends_on:
      - redis-master
    command:
      [
        'redis-server',
        '--replicaof',
        'redis-master',
        '6379',
        '--protected-mode',
        'no',
      ]

  sentinel-1:
    image: redis:latest
    ports:
      - "5000:26379"
    depends_on:
      - redis-master
      - redis-slave-1
      - redis-slave-2
    command: >
      sh -c 'echo "sentinel resolve-hostnames yes" > /etc/sentinel.conf &&
            echo "sentinel monitor mymaster redis-master 6379 2" >> /etc/sentinel.conf &&
            echo "sentinel down-after-milliseconds mymaster 1000" >> /etc/sentinel.conf &&
            echo "sentinel failover-timeout mymaster 5000" >> /etc/sentinel.conf &&
            echo "sentinel parallel-syncs mymaster 1" >> /etc/sentinel.conf &&
            redis-server /etc/sentinel.conf --sentinel'

  sentinel-2:
    image: redis:latest
    ports:
      - "5001:26379"
    depends_on:
      - redis-master
      - redis-slave-1
      - redis-slave-2
    command: >
      sh -c 'echo "sentinel resolve-hostnames yes" > /etc/sentinel.conf &&
            echo "sentinel monitor mymaster redis-master 6379 2" >> /etc/sentinel.conf &&
            echo "sentinel down-after-milliseconds mymaster 1000" >> /etc/sentinel.conf &&
            echo "sentinel failover-timeout mymaster 5000" >> /etc/sentinel.conf &&
            echo "sentinel parallel-syncs mymaster 1" >> /etc/sentinel.conf &&
            redis-server /etc/sentinel.conf --sentinel'

  sentinel-3:
    image: redis:latest
    ports:
      - "5002:26379"
    depends_on:
      - redis-master
      - redis-slave-1
      - redis-slave-2
    command: >
      sh -c 'echo "sentinel resolve-hostnames yes" > /etc/sentinel.conf &&
            echo "sentinel monitor mymaster redis-master 6379 2" >> /etc/sentinel.conf &&
            echo "sentinel down-after-milliseconds mymaster 1000" >> /etc/sentinel.conf &&
            echo "sentinel failover-timeout mymaster 5000" >> /etc/sentinel.conf &&
            echo "sentinel parallel-syncs mymaster 1" >> /etc/sentinel.conf &&
            redis-server /etc/sentinel.conf --sentinel'

  go-app:
    build: .
    depends_on:
      - sentinel-1
      - sentinel-2
      - sentinel-3

main.go

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/google/uuid"
	"github.com/redis/go-redis/v9"
)

func main() {
	redis := redis.NewFailoverClusterClient(&redis.FailoverOptions{
		MasterName: "mymaster",
		SentinelAddrs: []string{
			"sentinel-1:26379",
			"sentinel-2:26379",
			"sentinel-3:26379",
		},
		RouteRandomly: true,
	})

	for {
		key := uuid.NewString()
		err := redis.Set(context.Background(), key, "value", -1).Err()
		if err != nil {
			panic(err)
		}

		resp, err := redis.Get(context.Background(), key).Result()
		if err != nil && err.Error() != "redis: nil" {
			panic(err)
		}

		fmt.Println(key, resp)
		time.Sleep(1 * time.Second)
	}

}

dockerfile

FROM golang:1.21-alpine

WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go build -o main .

CMD ["./main"]

@ndyakov I think it would be a good idea, I'll update the README

[gopichanditv]

@htemelski-redis thanks for the clarification.

[ndyakov]

@gopichanditv marking this one as completed. @htemelski will update the readme when he has time.