Introduce Valkey client overview #164
Conversation
asafpamzn
commented
Aug 17, 2024
asafpamzn
commented
- Created a new document that provides an overview of recommended Valkey clients across various programming languages.
- Included mandatory features required for each client, such as Cluster Support and TLS/SSL Support.
- Detailed advanced features supported by the clients, including:
- Read from Replica
- Exponential Backoff to Prevent Storm
- Valkey Version Compatibility
- PubSub State Restoration
- Cluster Scan
- Latency-Based Read from Replica
- Client-Side Caching
- Added feature comparison tables for each programming language (Python, JavaScript/Node.js, Java, Go, PHP, C#) to highlight the unique capabilities of each client.
- Placeholder sections for Ruby and other languages marked as TODO for future updates.
- References section includes a link to the official Valkey documentation.
|
@asafpamzn Thank you for that initiative. it was discussed several times that we need some feature support metric for known clients. Several high level remarks:
|
|
@ranshid , thanks for the feedback.
|
|
@ranshid , @zuiderkwast , I updated the PR according to your comments. |
There was a problem hiding this comment.
I like the summary overall. @rueian @yangbodong22011 Would also be great if you can review this.
|
I think we can put all clients
|
I like this idea. If the table is large, it can be messy to maintain it as Markdown. If we have one JSON file per client (like we have for the old redis clients still in this repo), we could add this information in the JSON files and render the table on the website. |
agree👍 |
I don't agree, usually customers are first choosing the language and next the client, the client is a small part at the application, basically a driver. I don't think that the average reader will care about clients in other languages. I do agree that for the valkey maintainers it is a better view. |
- Created a new document that provides an overview of recommended Valkey clients across various programming languages. - Included mandatory features required for each client, such as Cluster Support and TLS/SSL Support. - Detailed advanced features supported by the clients, including: - Read from Replica - Exponential Backoff to Prevent Storm - Valkey Version Compatibility - PubSub State Restoration - Cluster Scan - Latency-Based Read from Replica - Client-Side Caching - Added feature comparison tables for each programming language (Python, JavaScript/Node.js, Java, Go, PHP, C#) to highlight the unique capabilities of each client. - Placeholder sections for Ruby and other languages marked as TODO for future updates. - References section includes a link to the official Valkey documentation. Signed-off-by: asafpamzn <[email protected]>
Co-authored-by: Avi Fenesh <[email protected]> Signed-off-by: asafpamzn <[email protected]>
…#159) Update cluster-slots docs ref: valkey-io/valkey#265 --------- Signed-off-by: Roshan Khatri <[email protected]> Signed-off-by: Madelyn Olson <[email protected]> Co-authored-by: Madelyn Olson <[email protected]> Signed-off-by: asafpamzn <[email protected]>
Add documentation for the new `info stats` fields. --------- Signed-off-by: Uri Yagelnik <[email protected]> Signed-off-by: asafpamzn <[email protected]>
Signed-off-by: asafpamzn <[email protected]>
Co-authored-by: Rueian <[email protected]> Signed-off-by: asafpamzn <[email protected]>
Signed-off-by: asafpamzn <[email protected]>
Signed-off-by: asafpamzn <[email protected]>
Signed-off-by: asafpamzn <[email protected]>
|
I think this will become very difficult to maintain if we have it as hand-written markdown. I'm generally in favour of having it generated from JSON @zuiderkwast suggested. The question for me is does that get generated as part of docs or website. Related: should this be in the man pages? The information could be useful but if they're mostly links out to GitHub repos it feels like that's more typically something someone would browse from the web, not from a terminal. |
@stockholmux , why do you think that it will be hard to maintain? It is up on the clients maintainers to update it once new feature is added. It does not happen that frequently. It should be part of the website, I agree |
|
@asafpamzn If something is represented as data (i.e. JSON), it's far more maintainable than hand written markdown which is difficult/time consuming to review and audit. As an example, some of the hand written markdown in the content we inherited in this repo was literally a decade out-of-date. No one reported this for years. Data we can query and answer questions quickly. Additionally, markdown fixes the format in markdown tables which is not sortable or filterable. If it's data, that we have more options. Finally, If we have it stored as data we can do represent of the data in different ways and in different places not just fixed into a single markdown file. |
My intuition is that all the specific client information shouldn't be part of the man pages. I feel like that is getting too low level to be materially useful to most individuals, and the clients are also updated independently from the rest of the code.
I suppose to extend this, we already have |
|
Hi all! Joining @asafpamzn in trying to move this PR along. I only did a short dive so correct me if I'm wrong or missing something (which may very well be the case), but from what I got from your conversation so far, assuming we're not adding to man pages, seems like we need to -
Did I get it right? |
Signed-off-by: lior sventitzky <[email protected]>
Update client json files and put client page in topics
|
There was a problem hiding this comment.
Great, so there will be a generated list of clients that can display this information?
The old list of clients used to be rendered on the URL redis.io/clients/. Most of our docs are from that time. There are already links to the page where the list of clients is supposed to be, i.e. the ../clients/ directory relative the topics directory.
I used grep to find some of them:
topics/cluster-tutorial.md:322:See the documentation for your [client of choice](../clients/) to determine its cluster support.
topics/eval-intro.md:176:Most of [Valkey' clients](../clients/) already provide utility APIs for doing that automatically.
topics/installation.md:85:You'll find a [full list of clients for different languages in this page](../clients/).
topics/introduction.md:33:You can use Valkey from [most programming languages](../clients/).
topics/ldb.md:234:LDB uses the client-server model where the Valkey server acts as a debugging server that communicates using [RESP](protocol.md). While `valkey-cli` is the default debug client, any [client](../clients/) can be used for debugging as long as it meets one of the following conditions:
topics/quickstart.md:22:The first step is to connect to Valkey. There are client connectors for [most programming languages](../clients/).
The website instead points these links to the page corresponding to topics/clients.md, which is about the handling of client connections (CLIENT LIST, CLIENT KILL, etc.). I don't know why, but I can only guess that it is to avoid broken links. @stockholmux do you want to confirm? Anyway, these links are supposed to point to the list of clients which used to be at the /clients/ URL.
topics/valkey-clients.md
Outdated
There was a problem hiding this comment.
There is already a page called topics/clients.md. It's about inspecting and handling the client connections using commads like CLIENT LIST, CLIENT KILL, etc.
The difference between the names valkey-clients ans clients is not making the difference between these two pages any clearer.
To distinguish them in a meaningful way and still avoid renaming the old one, we could call the new one client-libraries for example.
There was a problem hiding this comment.
We have a lot of existing links to valkey.io/clients/ on the web version, this is a hold over from the forked content.
For this file, I'd suggest something like client-list or something equally boring and descriptive.
As far as the valkey.io/clients/ path, once we have some sort of client path, I'll alias any existing links to the new page.
topics/valkey-clients.md
Outdated
| title: "Valkey Clients" | ||
| linkTitle: "Valkey Clients" |
There was a problem hiding this comment.
In the list of pages, we don't want all of them to start with Valkey.
I believe "linkTitle" is used in menues (@stockholmux correct me if I'm wrong!), where we see all of these together, and "title" is the title of the page.
For linkTitle, we don't want to repeat Valkey everywhere. We already have this for half of the pages and it looks like crap. See "Alphabetical index" on the page https://valkey.io/topics/ and scroll down.
There was a problem hiding this comment.
Clarification: The page itself doesn't look like crap. It's looks pretty good IMO. But it's not nice that half of them start with "Valkey".
There was a problem hiding this comment.
We no longer use linkTitle that was a hold the Jekyll version.
It does no harm but provides no value either.
There was a problem hiding this comment.
Good to know. So we can delete linkTitle to avoid confusion.
Should we skip "Valkey" in the page titles then, or use it in all page titles?
There was a problem hiding this comment.
@zuiderkwast (Slightly off topic)
Yeah, so it renders as <title>Valkey Documentation · Valkey persistence</title> which is a little silly.
Do you have a need for it to be "Valkey :topic:" vs just ":topic:"? If so, it's pretty trivial to just remove "Valkey" from the title string in the template rendering for things like the alphabetical index and document title. Feel free to put in an issue; I'm chewing through a backlog slowly.
I also have a PR in review that allows for conditional overrides of front matter directly into Zola so in the few edge cases where we might want to preserve 'Valkey' we can.
There was a problem hiding this comment.
Yes, I'd like to remove Valkey from all the titles in markdown, so it renders as "Valkey Documentation · Persistence" instead.
The alphabetical index looks especially silly when all or most of the entries start with Valkey.
There was a problem hiding this comment.
@viktor See PR that fixes this:
valkey-io/valkey-io.github.io#169
| @@ -0,0 +1,15 @@ | |||
| { | |||
There was a problem hiding this comment.
why is this an aws directory? GLIDE is a valkey project not AWS
| "language":"Go", | ||
| "read_from_replica": true, | ||
| "smart_backoff_to_prevent_connection_storm": true, | ||
| "valkey_version_compatibility": "7.2", |
There was a problem hiding this comment.
I don't understand this field: Valkey didn't change the API between 8.0 and 7.2 - what makes it 'compatible'?
There was a problem hiding this comment.
Supporting Valkey 8.0 features like AZ affinity, supporting new commands (like script show, cluster slot stats), and commands that were modified in 8.0.
| "AZ_based_read_from_replica": false, | ||
| "client_side_caching": false, | ||
| "client_capa_redirect": false, | ||
| "persistent_connection_pool": true |
There was a problem hiding this comment.
How does this take into account language specific properties? For example IIRC, valkey-py is synchronous or async, GLIDE is async. That's super relevant for someone picking a client in python but not at all for other languages.
There are others I'm sure as well.
There was a problem hiding this comment.
Maybe we could add a sentence to the description for this sort of stuff where it seems necessary? I think it's better to put it in the upper part and not in the feature table, it will get messy and the table focuses on the specific features that are explained above.
Do you have other ideas for worth mentioning criteria?
| "client_side_caching": false, | ||
| "client_capa_redirect": false, | ||
| "persistent_connection_pool": false | ||
| } |
There was a problem hiding this comment.
Another relevant property: package size. I'm not sure the metric, but GLIDE is quite large compared to other clients (as it needs to pull down the Rust binary stuff).
topics/valkey-clients.md
Outdated
| title: "Valkey Clients" | ||
| linkTitle: "Valkey Clients" |
There was a problem hiding this comment.
We no longer use linkTitle that was a hold the Jekyll version.
It does no harm but provides no value either.
topics/valkey-clients.md
Outdated
There was a problem hiding this comment.
We have a lot of existing links to valkey.io/clients/ on the web version, this is a hold over from the forked content.
For this file, I'd suggest something like client-list or something equally boring and descriptive.
As far as the valkey.io/clients/ path, once we have some sort of client path, I'll alias any existing links to the new page.
topics/valkey-clients.md
Outdated
|
|
||
| - **valkey-glide** | ||
| - GitHub: [valkey-glide](https://github.com/valkey-io/valkey-glide/tree/main/java) | ||
| - Installation: Available via Maven and Gradle |
There was a problem hiding this comment.
My preference would be to have a one-liner for ever Installation: field
topics/valkey-clients.md
Outdated
| - **Valkey-Java** | ||
| - GitHub: [valkey-java](https://github.com/valkey-io/valkey-java) | ||
| - Installation: Available via Maven and Gradle | ||
| - Description: valkey-java is Valkey's Java client, derived from Jedis fork, dedicated to maintaining simplicity and high performance. |
There was a problem hiding this comment.
'derived from Jedis fork' redundant?
topics/valkey-clients.md
Outdated
| ----- | ||
| - **valkey-go** | ||
| - GitHub: [go-valkey-go](https://github.com/valkey-io/valkey-go) | ||
| - Installation: TBD |
| @@ -0,0 +1,15 @@ | |||
| { | |||
There was a problem hiding this comment.
I'm not sure of the value of this directory structure (e.g.clients/go/github.com/valkey/valkey-go.json). Seems like some remnant of something that other datastore was doing.
It might be worth just moving stuff around to be: clients/go/valkey-go.json
There was a problem hiding this comment.
Do you mean for Go specifically or for all of the clients directory?
topics/valkey-clients.md
Outdated
| ----- | ||
| - **valkey-go** | ||
| - GitHub: [go-valkey-go](https://github.com/valkey-io/valkey-go) | ||
| - Installation: TBD |
There was a problem hiding this comment.
| - Installation: TBD | |
| - Installation: `go get github.com/valkey-io/valkey-go` |
⬆️ This is the command.
Signed-off-by: lior sventitzky <[email protected]>
Signed-off-by: lior sventitzky <[email protected]>
Signed-off-by: lior sventitzky <[email protected]>
|
|
Is there any PR for the website repo to render this page on the website? I'm thinking, the clients metadata is not really docs, is it? I mean, the docs repo is also used for man pages and potentially other formats, but we don't want to produce man pages with the client listings. If it's easier to just keep this metadata in the website repo, I will not oppose it. It may be easier to handle it. The docs repo and the website repo have different licenses, but is that a huge problem? These files are just a name and a link in most cases... |
@zuiderkwast |
|
@stockholmux WDYT? Keep this kind of content in the website repo? |
|
@zuiderkwast I'm not fully opposed to having it in the website repo. My hesitation is if the website repo has the right approval mechanisms: would the website maintainers have the right domain knowledge to make approvals on these. I know I feel relatively confident in say approving a PR, but it's totally possible that in the future we could website maintainers with less domain specific knowledge (e.g. they are experts in maintaining the website but not the nuance of, for example i, if I'd also like to get an opinion on moving this stuff to a different project with a different license, but I don't think this would be too much of an issue. The other option would be to split out all the client metadata into another repo. Which could make some sense if others want to consume this data (service providers, would be an example). |
Fair point. We can keep it in the doc repo then. I guess the main hassle is just now, to get this up in both repos. Once it's up, it shouldn't be too hard to update it.
Nah, that sounds too scattered to me. Let's just keep it in the doc repo. |
