docs: add Node Discovery Mode configuration guide - #295
Open
Aryex wants to merge 1 commit into
Open
Conversation
Aryex
added
AI Generated
documentation
Aryex
force-pushed
the
alexl/agent/csharp-node-discovery-mode
branch
from
July 26, 2026 21:26
78e85f6 to
bb59435
Compare
Signed-off-by: kiro-agent <kiro-agent@users.noreply.github.com>
Aryex
force-pushed
the
alexl/agent/csharp-node-discovery-mode
branch
from
July 27, 2026 14:56
bb59435 to
153cf1b
Compare
Aryex
marked this pull request as ready for review
July 27, 2026 14:56
currantw
reviewed
Jul 28, 2026
Comment on lines
+266
to
+307
| ## Limitations and Caveats | ||
|
|
||
| ### Static Mode + ClientName | ||
|
|
||
| Do not set a client name when using Static mode with a proxy. Proxies may not support the `CLIENT SETNAME` command that the client sends during connection setup, causing the connection to fail. | ||
|
|
||
| ### DiscoverAll — One-Time Discovery | ||
|
|
||
| Discovery happens only at client creation time. Topology changes that occur after the client is created (e.g., a new replica joining) are not re-discovered. To pick up topology changes, recreate the client. | ||
|
|
||
| ### DiscoverAll + Read-Only Are Mutually Exclusive | ||
|
|
||
| DiscoverAll mode requires `INFO REPLICATION` to discover the topology. Read-only mode skips this command. Because of this conflict, combining DiscoverAll with read-only mode is rejected at client creation time. | ||
|
|
||
| ### Standalone Mode Only | ||
|
|
||
| NodeDiscoveryMode is only relevant for standalone clients. In cluster mode, the client uses its own built-in topology discovery mechanism, and this setting is ignored. | ||
|
|
||
| ## When to Use Each Mode | ||
|
|
||
| ### Standard (default) | ||
|
|
||
| Use Standard mode when: | ||
| - You are connecting directly to Valkey nodes (no proxy in between) | ||
| - You want the client to verify which node is the primary and which are replicas | ||
| - You are providing addresses for all nodes you want the client to connect to | ||
|
|
||
| This is the safest and most common choice. Existing code continues to work without changes. | ||
|
|
||
| ### Static | ||
|
|
||
| Use Static mode when: | ||
| - Connecting through a proxy (Envoy, Twemproxy, HAProxy) that does not support `INFO REPLICATION` | ||
| - The topology is known and will not change (e.g., a single-node deployment) | ||
| - You want to minimize connection setup overhead by skipping role verification | ||
|
|
||
| ### DiscoverAll | ||
|
|
||
| Use DiscoverAll mode when: | ||
| - You want to connect to all nodes in a replication group but only know one node's address | ||
| - You are using `PreferReplica` read strategy and want the client to automatically find replicas | ||
| - Your infrastructure provides a single entry point but the client should spread reads across replicas |
Collaborator
There was a problem hiding this comment.
I think it makes sense to incorporate this information into the section for each mode above, rather than in separate section (keep all info for a particular mode in one place).
|
|
||
| Standard is the default — no configuration needed. The client sends `INFO REPLICATION` to each provided address to verify node roles. | ||
|
|
||
| <Tabs syncKey="progLangInExamples"> |
Collaborator
There was a problem hiding this comment.
Are ALL these examples necessary? They only differ by a single line, so seems like just one example for each language would be fine?
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
4 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.
Summary
Add documentation for the
NodeDiscoveryModeconfiguration option that controls how standalone clients discover node roles and topology during connection initialization.Source Commits
bf3f63e— AddNodeDiscoveryModeconfiguration option for standalone clients (#455)Changes
how-to/connections/node-discovery-mode.mdxdocumenting:astro.config.mjssidebar to include the new page in the Connections sectionContext
C# #455 implements
NodeDiscoveryModefor the C# standalone client, bringing it in line with the other language bindings (Python, Java, Node.js, Go) from valkey-glide #5724. The feature enables proxy compatibility (Static mode skipsINFO REPLICATION) and auto-discovery of replicas (DiscoverAll mode). This documentation covers all language clients since the feature was previously undocumented.cc @jamesx-improving
This PR was generated by the automated documentation pipeline.