Introduce Valkey client overview #164
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| { | ||
| "name": "valkey-go", | ||
| "description": "A fast Golang Valkey client that does auto pipelining and supports server-assisted client-side caching.", | ||
| "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 There was a problem hiding this comment. gotcha. This is more of a version compliance number than compatibility field. Might be good the make that clear in the identifier. |
||
| "pubsub_state_restoration": true, | ||
| "cluster_scan": false, | ||
| "latency_based_read_from_replica": false, | ||
| "AZ_based_read_from_replica": false, | ||
| "client_side_caching": true, | ||
| "client_capa_redirect": false, | ||
| "persistent_connection_pool": true | ||
| } | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| { | ||
|
There was a problem hiding this comment. why is this an |
||
| "name": "Valkey GLIDE", | ||
| "description": "General Language Independent Driver for the Enterprise (GLIDE) for Redis is an advanced multi-language Redis client that is feature rich, highly performant, and built for reliability and operational stability. GLIDE for Redis is supported by AWS.", | ||
| "language":"Java", | ||
| "read_from_replica": true, | ||
| "smart_backoff_to_prevent_connection_storm": true, | ||
| "valkey_version_compatibility": "8.0", | ||
| "pubsub_state_restoration": true, | ||
| "cluster_scan": true, | ||
| "latency_based_read_from_replica": false, | ||
| "AZ_based_read_from_replica": true, | ||
| "client_side_caching": false, | ||
| "client_capa_redirect": false, | ||
| "persistent_connection_pool": false | ||
| } | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| { | ||
| "name": "valkey-java", | ||
| "description": "valkey-java is Valkey's Java client, derived from Jedis fork, dedicated to maintaining simplicity and high performance.", | ||
| "language":"Java", | ||
| "read_from_replica": false, | ||
| "smart_backoff_to_prevent_connection_storm": true, | ||
| "valkey_version_compatibility": "7.2", | ||
| "pubsub_state_restoration": false, | ||
| "cluster_scan": false, | ||
| "latency_based_read_from_replica": false, | ||
| "AZ_based_read_from_replica": false, | ||
| "client_side_caching": false, | ||
| "client_capa_redirect": false, | ||
| "persistent_connection_pool": true | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| { | ||
| "name": "Valkey GLIDE", | ||
| "description": "General Language Independent Driver for the Enterprise (GLIDE) for Redis is an advanced multi-language Redis client that is feature rich, highly performant, and built for reliability and operational stability. GLIDE for Redis is supported by AWS.", | ||
| "language":"Node.js", | ||
| "read_from_replica": true, | ||
| "smart_backoff_to_prevent_connection_storm": true, | ||
| "valkey_version_compatibility": "8.0", | ||
| "pubsub_state_restoration": true, | ||
| "cluster_scan": true, | ||
| "latency_based_read_from_replica": false, | ||
| "AZ_based_read_from_replica": true, | ||
| "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). |
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| { | ||
| "name": "iovalkey", | ||
| "description": "A robust, performance-focused and full-featured Redis client for Node.js.", | ||
| "language":"Node.js", | ||
| "read_from_replica": true, | ||
| "smart_backoff_to_prevent_connection_storm": true, | ||
| "valkey_version_compatibility": "7.2", | ||
| "pubsub_state_restoration": false, | ||
| "cluster_scan": false, | ||
| "latency_based_read_from_replica": false, | ||
| "AZ_based_read_from_replica": false, | ||
| "client_side_caching": false, | ||
| "client_capa_redirect": false, | ||
| "persistent_connection_pool": true | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,8 +1,19 @@ | ||
| { | ||
| "name": "Predis", | ||
| "description": "A flexible and feature-complete Redis client for PHP.", | ||
| "recommended": true, | ||
| "twitter": [ | ||
| "JoL1hAHN" | ||
| ], | ||
| "language":"PHP", | ||
| "read_from_replica": true, | ||
| "smart_backoff_to_prevent_connection_storm": true, | ||
| "valkey_version_compatibility": "7.2", | ||
| "pubsub_state_restoration": false, | ||
| "cluster_scan": false, | ||
| "latency_based_read_from_replica": false, | ||
| "AZ_based_read_from_replica": false, | ||
| "client_side_caching": true, | ||
| "client_capa_redirect": false, | ||
| "persistent_connection_pool": false | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,21 @@ | ||
| { | ||
| "name": "phpredis", | ||
| "description": " A PHP extension for Redis, offering high performance and a native API.", | ||
| "recommended": true, | ||
| "twitter": [ | ||
| "grumi78", | ||
| "yowgi", | ||
| "yatsukhnenko" | ||
| ], | ||
| "language":"PHP", | ||
| "read_from_replica": true, | ||
| "smart_backoff_to_prevent_connection_storm": true, | ||
| "valkey_version_compatibility": "7.2", | ||
| "pubsub_state_restoration": false, | ||
| "cluster_scan": false, | ||
| "latency_based_read_from_replica": false, | ||
| "AZ_based_read_from_replica": false, | ||
| "client_side_caching": true, | ||
| "client_capa_redirect": false, | ||
| "persistent_connection_pool": true | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| { | ||
| "name": "Valkey GLIDE", | ||
| "description": "General Language Independent Driver for the Enterprise (GLIDE) for Redis is an advanced multi-language Redis client that is feature rich, highly performant, and built for reliability and operational stability. GLIDE for Redis is supported by AWS.", | ||
|
There was a problem hiding this comment. "for Redis" ? This needs some work. |
||
| "language":"Python", | ||
| "read_from_replica": true, | ||
| "smart_backoff_to_prevent_connection_storm": true, | ||
| "valkey_version_compatibility": "8.0", | ||
| "pubsub_state_restoration": true, | ||
| "cluster_scan": true, | ||
| "latency_based_read_from_replica": false, | ||
| "AZ_based_read_from_replica": true, | ||
| "client_side_caching": false, | ||
| "client_capa_redirect": false, | ||
| "persistent_connection_pool": false | ||
| } | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| { | ||
| "name": "valkey-py", | ||
| "description": "The Python interface to the Valkey key-value store.", | ||
| "language":"Python", | ||
| "read_from_replica": true, | ||
| "smart_backoff_to_prevent_connection_storm": true, | ||
| "valkey_version_compatibility": "7.2", | ||
| "pubsub_state_restoration": false, | ||
| "cluster_scan": false, | ||
| "latency_based_read_from_replica": false, | ||
| "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, 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. There was a problem hiding this comment. We should probably add some sort of semi-free form array for high specific features. That way we can render them in the same way instead of making people read the description paragraphs. |
||
| } | ||
|
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 To distinguish them in a meaningful way and still avoid renaming the old one, we could call the new one There was a problem hiding this comment. We have a lot of existing links to For this file, I'd suggest something like As far as the |
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,105 @@ | ||||||
| --- | ||||||
| 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 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) 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 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: |
||||||
| description: Overview of Valkey clients and features | ||||||
| --- | ||||||
|
|
||||||
| Selecting the right client is a complex task, given that there are over 200 clients compatible with Valkey across different programming languages. This document offers an overview of recommended Valkey clients for various programming languages. To be included in this list, a client must support a mandatory set of features, such as TLS support and cluster mode. Additionally, for each language, we have provided a list of advanced features supported by the respective clients, highlighting the unique advantages of one client over another. | ||||||
|
There was a problem hiding this comment. Were all 200 evaluated to make this recommendation? There was a problem hiding this comment. Drop 'we' here - it's ambiguous. As a reader I don't know who 'we' and it changes the grammatical voice randomly. There was a problem hiding this comment. agree, fixed the text. |
||||||
|
|
||||||
| Mandatory Features Overview | ||||||
| ---- | ||||||
| 1. **Cluster Support** - The ability to operate in a clustered environment, where the data is distributed across multiple shards. Cluster support is essential for applications that require high scalability. | ||||||
|
|
||||||
| 2. **TLS/SSL Support** - The capability to establish secure connections using TLS/SSL, which encrypts the data transmitted between the client and the server. This is a critical feature for applications that require data privacy and protection against eavesdropping. | ||||||
|
|
||||||
| Advanced Features Overview | ||||||
| ----- | ||||||
|
|
||||||
| 1. **Read from Replica** - The ability to read data from a replica node, which can be useful for load balancing and reducing the load on the primary node. This feature is particularly important in read-heavy applications. | ||||||
|
|
||||||
| 2. **Smart Backoff to Prevent Connection Storm** - A strategy used to prevent connection storms by progressively updating the wait time between retries when attempting to reconnect to a Valkey server. This helps to reduce the load on the server during topology updates, periods of high demand or network instability. | ||||||
|
|
||||||
| 3. **Valkey Version Compatibility** - Indicates which versions of Valkey the client is compatible with. This is crucial for ensuring that the client can leverage the latest features and improvements in the Valkey server. | ||||||
|
|
||||||
| 4. **PubSub State Restoration** - The ability to restore the state of Pub/Sub (publish/subscribe) channels after a client reconnects. This feature ensures that clients can continue receiving messages after disconnections or topology updates such as adding or removing shards, for both legacy Pub/Sub and sharded Pub/Sub. The client will automatically resubscribe the connections to the new node. The advantage is that the application code is simplified, and doesn’t have to take care of resubscribing to new nodes during reconnects. | ||||||
|
|
||||||
| 5. **Cluster Scan** - This feature ensures that the user experience and guarantees for scanning a cluster are identical to those for scanning a single node. The SCAN function operates as a cursor-based iterator. With each command, the server provides an updated cursor, which must be used as the cursor argument in subsequent calls. A complete iteration with SCAN retrieves all elements present in the collection from start to finish. If an element exists in the collection at the beginning and remains until the end of the iteration, SCAN will return it. Conversely, any element removed before the iteration begins and not re-added during the process will not be returned by SCAN. A client supporting this feature ensures the scan iterator remains valid even during failovers or cluster scaling (in or out) during the SCAN operation. | ||||||
|
|
||||||
| 6. **Latency-Based Read from Replica** - This feature enables reading data from the nearest replica, i.e., the replica that offers the best latency. It supports complex deployments where replicas are distributed across various distances, including different geographical regions, to ensure data is read from the closest replica, thereby minimizing latency. | ||||||
|
|
||||||
| 7. **AZ-Based Read from Replica** - This feature enables reading data from replicas within the same Availability Zone (AZ). When running Valkey in a cloud environment across multiple AZs, it is preferable to keep traffic localized within an AZ to reduce costs and latency. By reading from replicas in the same AZ as the client, you can optimize performance and minimize cross-AZ data transfer charges. For more detailed information about this feature and its implementation, please refer to the following link: https://github.com/valkey-io/valkey/pull/700 | ||||||
|
|
||||||
| 8. **Client Side Caching** - Valkey client-side caching is a feature that allows clients to cache the results of Valkey queries on the client-side, reducing the need for frequent communication with the Valkey server. This can significantly improve application performance by lowering latency, reducing the network usage and cost and reducing the load on the Valkey server. | ||||||
|
|
||||||
| 9. **`CLIENT CAPA redirect` Support** - The `CLIENT CAPA redirect` feature was introduced in Valkey 8 to facilitate seamless upgrades without causing errors in standalone mode. When enabled, this feature allows the replica to redirect data access commands (both read and write operations) to the primary instance. This ensures uninterrupted service during the upgrade process. For more detailed information about this feature, please refer to the following link: https://github.com/valkey-io/valkey/pull/325 | ||||||
|
|
||||||
| 10. **Persistent Connection Pool** - This feature enables the Valkey client to maintain a pool of persistent connections to the Valkey server, improving performance and reducing overhead. Instead of establishing a new connection for each request, the client can reuse existing connections from the pool, minimizing the time and resources required for connection setup. | ||||||
|
|
||||||
| Table of Contents | ||||||
| ---- | ||||||
| - [Table of Contents](#table-of-contents) | ||||||
| - [Python](#python) | ||||||
| - [JavaScript/Node.js](#javascriptnodejs) | ||||||
| - [Java](#java) | ||||||
| - [Go](#go) | ||||||
| - [PHP](#php) | ||||||
|
|
||||||
|
|
||||||
| Python | ||||||
| ----- | ||||||
| - **valkey-glide** | ||||||
| - GitHub: [valkey-glide](https://github.com/valkey-io/valkey-glide/tree/main/python) | ||||||
| - Installation: `pip install valkey-glide` | ||||||
| - Description: Valkey GLIDE is designed for reliability, optimized performance, and high-availability, for Valkey and Redis OSS based applications. GLIDE is a multi language client library, written in Rust with programming language bindings, such as Java, node.js and Python. | ||||||
|
There was a problem hiding this comment. How is this different from the content in the JSON file? IMHO, move all this stuff into the JSON and generate this stuff. |
||||||
|
|
||||||
| - **valkey-py** | ||||||
| - GitHub: [valkey-py](https://github.com/valkey-io/valkey-py) | ||||||
| - Installation: `pip install valkey` | ||||||
| - Description: The Python interface to the Valkey key-value store. | ||||||
|
|
||||||
|
|
||||||
| JavaScript/Node.js | ||||||
| ---- | ||||||
| - **valkey-glide** | ||||||
| - GitHub: [valkey-glide](https://github.com/valkey-io/valkey-glide/tree/main/node) | ||||||
| - Installation: `npm install valkey-glide` | ||||||
| - Description: Valkey GLIDE is designed for reliability, optimized performance, and high-availability, for Valkey and Redis OSS based applications. GLIDE is a multi language client library, written in Rust with programming language bindings, such as Java, node.js and Python. | ||||||
|
|
||||||
| - **iovalkey** | ||||||
| - GitHub: [iovalkey](https://github.com/valkey-io/iovalkey) | ||||||
| - Installation: `npm install iovalkey` | ||||||
| - Description: A robust, performance-focused and full-featured Redis client for Node.js. This is a friendly fork of ioredis after this commit. | ||||||
|
|
||||||
| Java | ||||||
| ---- | ||||||
|
|
||||||
| - **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 |
||||||
| - Description: Valkey GLIDE is designed for reliability, optimized performance, and high-availability, for Valkey and Redis OSS based applications. GLIDE is a multi language client library, written in Rust with programming language bindings, such as Java, node.js and Python. | ||||||
|
|
||||||
| - **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? |
||||||
|
|
||||||
|
|
||||||
| Go | ||||||
| ----- | ||||||
| - **valkey-go** | ||||||
| - GitHub: [go-valkey-go](https://github.com/valkey-io/valkey-go) | ||||||
| - Installation: TBD | ||||||
|
There was a problem hiding this comment.
Suggested change
⬆️ This is the command. |
||||||
| - Description: A fast Golang Valkey client that does auto pipelining and supports server-assisted client-side caching. | ||||||
|
|
||||||
|
|
||||||
| PHP | ||||||
| ---- | ||||||
| - **Predis** | ||||||
| - GitHub: [Predis](https://github.com/predis/predis) | ||||||
| - Installation: `composer require predis/predis` | ||||||
| - Description: A flexible and feature-rich Valkey client for PHP. | ||||||
|
|
||||||
| - **phpredis** | ||||||
| - GitHub: [phpredis](https://github.com/phpredis/phpredis) | ||||||
| - Installation: Install via PECL or compile from source | ||||||
| - Description: A PHP extension for Redis, offering high performance and a native API. | ||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.jsonThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do you mean for Go specifically or for all of the clients directory?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As per the sync off GitHub, my indication was that we should get rid of the strange inherited directory structure and flatten this moving forward. IIRC @zuiderkwast and I also had a similar conversation a while back.
My opinion on the pre-existing client JSON files that aren't included in this PR is that should be moved elsewhere since they aren't used here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, I agree. Instead of encoding the URL in the file path, we can add a JSON field like
"repository": "https://github.com/ptaoussanis/carmine"(an actively maintained Closure client). It used do be this way before the commit 32574aa but then, all clients were in one huge JSON file. That's not good either. I suggest we put them asclients/LANGUAGE/NAME.json. I don't think there are name collissions for the same language.Here I'm of a different opinion.
There are clients in 56 languages, many that probably still work. Many users only use GET and SET anyway and even for those users, latest Valkey has a lot of improvememts. Until the fork happened, I know people regularly contributed clients to this list. The last one was for the Balleria language IIRC. Languages like Scheme, R, Objective-C, Clojure, etc. have a lot of users and listing them shows how huge the community is (or has been) IMO. Redis obviously ignores the community efforts, but I think it's a bad idea to do the same. I think we should list them, but with a disclaimer. We can even hide them by default but present a checkbox Show 3rd party clients or so. They're just links and we can't verify the quality of each of them.
For the rendering code, it's easy to detect an old client by checking if the JSON file contain some field like
"valkey_version_compatibility". If it doesn't, it means it's old and we didn't verify the compatibility. We need the client users or authors to verify this and update the information. For that to happen, they need to be visible somewhere.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@zuiderkwast WRT the other client JSON files, I'm more/less okay the trajectory you describe.
I guess I'm mostly concerned with unblocking the
/clients/page which explicitly about Valkey clients and only lists the specific clients outlined here.The other clients are Redis clients (which should work and I'm fine) but manipulating all other ones doesn't actually move anything forward today for the docs nor website.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OK, fine. Incremental perfection. :)