From 83557c9701698dd4711e06ad36bd3c0acaf6be8b Mon Sep 17 00:00:00 2001 From: Nathan Friedly Date: Tue, 12 Aug 2025 10:13:40 -0400 Subject: [PATCH] Clustering sendCommand docs We noticed that `sendCommand()` takes different arguments for clusters vs clients, and I wanted to document the differences. I think I got it correct, but please review closely just to be sure. It might also be worth adding a note to [the readme](https://github.com/redis/node-redis/blob/2f106324507eec905b8fe7691ba11179acdeeca7/README.md#L136-L144) also, since this is a somewhat unexpected difference, what do you think? Relates to https://github.com/express-rate-limit/rate-limit-redis/issues/207 & https://github.com/express-rate-limit/rate-limit-redis/pull/208 --- docs/clustering.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/clustering.md b/docs/clustering.md index 6803583fa5..3e4f8446b6 100644 --- a/docs/clustering.md +++ b/docs/clustering.md @@ -38,6 +38,25 @@ await cluster.close(); | scripts | | Script definitions (see [Lua Scripts](./programmability.md#lua-scripts)) | | functions | | Function definitions (see [Functions](./programmability.md#functions)) | +## Usage + +Most redis commands are the same as with individual clients. + +### Unsupported Redis Commands + +If you want to run commands and/or use arguments that Node Redis doesn't know about (yet!) use `.sendCommand()`. + +When clustering, `sendCommand` takes 3 arguments to help with routing to the correct redis node: +* `firstKey`: the key that is being operated on, or `undefined` to route to a random node. +* `isReadOnly`: determines if the command needs to go to the master or may go to a replica. +* `args`: the command and all arguments (including the key), as an array of strings. + +```javascript +await cluster.sendCommand("key", false, ["SET", "key", "value", "NX"]); // 'OK' + +await cluster.sendCommand("key", true, ["HGETALL", "key"]); // ['key1', 'field1', 'key2', 'field2'] +``` + ## Auth with password and username Specifying the password in the URL or a root node will only affect the connection to that specific node. In case you want to set the password for all the connections being created from a cluster instance, use the `defaults` option. @@ -114,3 +133,4 @@ Admin commands such as `MEMORY STATS`, `FLUSHALL`, etc. are not attached to the ### "Forwarded Commands" Certain commands (e.g. `PUBLISH`) are forwarded to other cluster nodes by the Redis server. The client sends these commands to a random node in order to spread the load across the cluster. +