Repository navigation
DOC-7167 Add Redis Sentinel connection examples to client connect pages - #4229
Open
andy-stark-redis wants to merge 1 commit into
Open
andy-stark-redis wants to merge 1 commit into
andy-stark-redis wants to merge 1 commit into
Conversation
Adds a "Connect to Redis Sentinel" section after the cluster section on the nine connect.md pages (H3 on Jedis to match its neighbors). hiredis gets a short "not supported" section: v1.4.1 has no Sentinel code. Every snippet ran against a local topology (primary, replica, three Sentinels, mymaster, quorum 2) in two variants: no auth, and separate data-node and Sentinel passwords. Test copies differed from the page snippets only in ports, passwords, and key names. Versions run: redis-py 8.1.0 (GitHub tag source), go-redis v9.23.0, node-redis 6.3.0, ioredis 6.0.0, Jedis 8.0.2, Lettuce 7.8.0, StackExchange.Redis 3.0.0 (NuGet was blocked; latest is 3.3.1), Predis 3.6.1. The failover caveats are measured, not inferred. Under a forced SENTINEL FAILOVER, redis-py, ioredis (default options), a Lettuce RedisClient connection, Predis, and SE.Redis 3.0.0 kept writing to the demoted primary for about 10 s, until Sentinel reconfigured it, and the old primary discarded those acknowledged writes on resync (22 of about 60 in the measured runs). go-redis, node-redis, and Jedis subscribe to +switch-master and moved within 1-2 s; ioredis with failoverDetector cut loss to the inherent sub-second window. The .NET page deliberately has no caveat: 3.3.1 adds an IsStalePrimaryView path that may close the window, and 3.3.1 couldn't be run here (needs the .NET 10 SDK). Surprises worth knowing before editing these sections: Jedis RedisSentinelClient has no replica reads at all; Predis replica routing is sticky until the first write and the parameters username leaks to the Sentinels (hence username in each Sentinel URI); go-redis ReplicaOnly sends writes to the replica too; redis-py sentinel_kwargs stops socket_* inheritance. Learned: five of eight clients silently lose ~10 s of writes after a graceful Sentinel failover Constraint: every snippet here is run-verified (some trimmed to fragments of the tested program); re-run any edit against a real Sentinel topology Rejected: SE.Redis SentinelUser/SentinelPassword options | 3.1.13+, source-read only, never run; page uses SentinelConnect + GetSentinelMasterConnection, which ran on 3.0.0 Rejected: Jedis .serverDefaultProtocol() to silence the 8.x RESP3 WARN | method doesn't exist in 7.x Directive: add the SE.Redis failover caveat only after testing 3.3.1 or later under a forced failover Directive: link Sentinel URL forms to connection-urls.md once DOC-7165 merges; it isn't on main yet Gaps: no TLS to Sentinels tested on any client; no crash failover, only graceful SENTINEL FAILOVER; SE.Redis 3.3.1 never run Recheck: SE.Redis credentials example when the .NET 10 SDK is available to run 3.3.1 Ticket: DOC-7167 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
Contributor
Contributor
🧠 Redis MemoryFound 5 related items from repository history (5 new this commit):
Memory updated at 83aaa16 |
This was referenced Oct 8, 2026
kaitlynmichael
approved these changes
Oct 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a "Connect to Redis Sentinel" section to each client connect page, right after the cluster section. Fixes DOC-7167, part of epic DOC-7164.
What's on each page
slave_for()ReplicaOnlyreplicaPoolSizerole: "slave"failoverDetectorMasterReplica+ReadFromRedisClientSentinelConnect()two-step formCommandFlags.PreferReplicaHow the examples were tested
Every snippet was run against a local Sentinel setup: one primary, one replica, and three Sentinels watching
mymaster(failover needs 2 of the 3 to agree). There were two variants: one with no auth, and one with different passwords for the data nodes and the Sentinels. The test copies differed from the page snippets only in ports, passwords and key names.Versions tested:
Please review: the failover caveats
We forced failovers with
SENTINEL FAILOVER. Four clients kept writing to the old primary for about 10 seconds, until Sentinel turned it into a replica: redis-py, ioredis (default options), LettuceRedisClient, and Predis. The old primary then discarded those writes, even though the client had received a success reply for each one. We measured 22 lost writes out of about 60.go-redis, node-redis and Jedis listen for Sentinel's
+switch-masterannouncement and switched within 1–2 seconds. The caveats on the four affected pages describe this behavior. They're based on our tests, not on any client's own documentation.Not in this PR
connection-urls.md. That page is still in an open DOC-7165 PR; I'll add the links once it merges.SentinelUser/SentinelPasswordoptions (3.1.13+) were checked in the source code but couldn't be run. The page shows the two-step form, which did run on 3.0.0.🤖 Generated with Claude Code
Note
Low Risk
Documentation-only changes to client connect guides; no application or runtime code is modified.
Overview
Adds a Connect to Redis Sentinel section (placed after the cluster section) on nine client
connect.mdpages, with runnable examples for discovering the primary via Sentinels, split Sentinel vs data-node credentials, and replica read patterns where each client supports them.Several pages document failover behavior: redis-py, ioredis (recommends
failoverDetector), Lettuce (RedisClientvsMasterReplica), and Predis warn that the client may keep writing to the demoted primary until Sentinel closes the connection. hiredis gets an explicit note that Sentinel is unsupported. Jedis documents primary-only use (no replica reads).Reviewed by Cursor Bugbot for commit 83aaa16. Bugbot is set up for automated code reviews on this repo. Configure here.