ioredis

You can scale your cluster by directing read queries to slave nodes using the scaleReads option. By default, scaleReads is set to "master" (only masters are queried).

Available options for scaleReads:

1. "all": Write queries go to masters; read queries go to masters or slaves randomly.
2. "slave": Write queries go to masters; read queries go to slaves.
3. function(nodes, command): A custom selection function. The first node in nodes is always the master for the relevant slots. If the function returns an array, a random node from that array is selected.

Warning: When using "slave", results might be stale due to replication lag between master and slave.

const cluster = new Redis.Cluster(
  [
    /* nodes */
  ],
  {
    scaleReads: "slave",
  }
);
cluster.set("foo", "bar"); // Sent to a master
cluster.get("foo", (err, res) => {
  // Sent to a slave
});

ioredis supports the Publish–subscribe pattern using Node.js events.

Important: A single Redis instance cannot act as both a publisher and a subscriber simultaneously. When subscribe() or psubscribe() is called, the connection enters 'subscriber mode', where only subscription-related commands (like ping, quit, unsubscribe) are valid. To publish messages while also listening for them in the same process, you must create two separate Redis instances.

const Redis = require("ioredis");

// To use both roles, create two instances
const sub = new Redis();
const pub = new Redis();

// Subscriber setup
sub.subscribe("my-channel", (err, count) => {
  console.log(`Subscribed to ${count} channels`);
});

sub.on("message", (channel, message) => {
  console.log(`Received ${message} from ${channel}`);
});

// Pattern subscription
sub.psubscribe("pat*ern", (err, count) => {});
sub.on("pmessage", (pattern, channel, message) => {});

// Publisher usage
pub.publish("my-channel", "Hello World");

ioredis publishes telemetry through Node.js diagnostics_channel, allowing APM tools to observe commands, connections, and batch operations without modifying application code. This requires Node.js >= 18.19.0.

Sub-events include start, end, asyncStart, asyncEnd, and error. You subscribe using the pattern tracing:ioredis:<type>:<event>.

Available channels:

• ioredis:command: Individual commands (standalone, pipeline, or MULTI).
• ioredis:batch: Entire MULTI transactions.
• ioredis:connect: Socket connection attempts.

Note on Security: Command arguments are sanitized. Sensitive values in commands like SET or AUTH are replaced with ?. Read-only commands like GET and DEL retain all arguments.

import dc from "node:diagnostics_channel";

dc.subscribe("tracing:ioredis:command:start", ({ command, args }) => {
  console.log(`> ${command}`, args);
});

dc.subscribe("tracing:ioredis:command:asyncEnd", ({ command }) => {
  console.log(`${command} settled`);
});

dc.subscribe("tracing:ioredis:command:error", ({ command, error }) => {
  console.error(`${command} failed:`, error);
});

ioredis supports Redis Sentinel for high availability. When connecting via Sentinel, ioredis guarantees that the node you connect to is always a master (or a slave if role: 'slave' is specified), even during failovers. During a failover, commands are queued and executed once the new master is established.

Key Sentinel Options:

• sentinels: An array of { host, port } objects for Sentinel instances.
• name: The name of the Sentinel group (e.g., mymaster).
• sentinelPassword: (Optional) Password for Sentinel instances.
• role: Set to slave to connect to a random slave instead of the master.
• preferredSlaves: (Optional) A function or array to prioritize specific slaves.
• enableTLSForSentinelMode: (Optional) Set to true if connecting to encrypted Sentinel instances.
• sentinelRetryStrategy: (Optional) A function invoked when all Sentinel nodes are unreachable.

const redis = new Redis({
  sentinels: [
    { host: "localhost", port: 26379 },
    { host: "localhost", port: 26380 },
  ],
  name: "mymaster",
});

redis.set("foo", "bar");

Redis Streams can be used as communication channels or log-like data structures. To consume messages, use the xread command with the BLOCK option. This allows you to wait for new data to arrive. When consuming, you typically pass the ID of the last processed message to the next xread call to continue from where you left off.

const Redis = require("ioredis");
const redis = new Redis();

const processMessage = (message) => {
  console.log("Id: %s. Data: %O", message[0], message[1]);
};

async function listenForMessage(lastId = "$") {
  // results is an array of [key, messages]
  const results = await redis.xread("BLOCK", 0, "STREAMS", "mystream", lastId);
  const [key, messages] = results[0];

  messages.forEach(processMessage);

  // Pass the last id of the results to the next round.
  await listenForMessage(messages[messages.length - 1][0]);
}

listenForMessage();

Standard Pub/Sub in a cluster broadcasts messages across all nodes, which has scalability limits. For better scalability, use Sharded Pub/Sub with the spublish and ssubscribe commands.

Requirements:

1. You must enable shardedSubscribers: true in the Redis.Cluster options.
2. All channel names in a single ssubscribe call must map to the same hash slot.
3. You can call ssubscribe multiple times to subscribe to different slots.

Listen for messages using the smessage event.

const cluster: Cluster = new Cluster([{ host: host, port: port }], {
  shardedSubscribers: true,
});

// Register the callback
cluster.on("smessage", (channel, message) => {
  console.log(message);
});

// Subscribe to the channels on the same slot
cluster
  .ssubscribe("channel{my}:1", "channel{my}:2")
  .then((count: number) => {
    console.log(count);
  })
  .catch((err: any) => {
    console.log(err);
  });

// Publish a message
cluster
  .spublish("channel{my}:1", "This is a test message to my first channel.")
  .then((value: number) => {
    console.log("Published a message to channel{my}:1");
  });