Overview

A Redis Cluster splits the keys across 16384 hash slots, and each primary owns a range of them. layerCluster discovers the topology, sends every command to the node that owns its slot, and follows MOVED and ASK redirects. The Redis API is the same as on a standalone server.

Example (Connecting to a Cluster)

import { Effect } from "effect";
import { Redis } from "@effect-kit/redis";
import { RedisNode } from "@effect-kit/redis/node";

const ClusterLive = RedisNode.layerCluster({
  url: "redis://localhost:7000",
  cluster: {
    seeds: [
      { host: "localhost", port: 7001 },
      { host: "localhost", port: 7002 },
    ],
  },
});

const program = Effect.gen(function* () {
  const redis = yield* Redis;
  yield* redis.set("user:42", "Ada");
  return yield* redis.get("user:42");
});

export const runnable = program.pipe(Effect.provide(ClusterLive));

The address in url or endpoint is the first seed, and cluster.seeds adds more. The layer asks the seeds for the topology when it is built, so an unreachable cluster fails at startup. RedisBun.layerCluster takes the same input. Cluster needs TCP endpoints: a Unix socket fails with RedisConfigError. Cluster is not available over Upstash HTTP.

Provided servicesCopy Anchor Link

The cluster layer provides Redis, RedisCluster, CommandExecutor, BatchExecutor and RedisCredentials.

Example (The Services a Cluster Layer Provides)

import type { Layer } from "effect";
import { RedisNode } from "@effect-kit/redis/node";

const ClusterLive = RedisNode.layerCluster({
  url: "redis://localhost:7000",
});

type Provided = Layer.Success<typeof ClusterLive>;
       
type Provided = BatchExecutor | CommandExecutor | Crypto | Redis | RedisCluster | RedisCredentials

Reaching a node with RedisClusterCopy Anchor Link

RedisCluster takes a target: { key } routes to the node that owns the key's slot, and { node } names a node by id.

Example (Running a Blocking Pop on the Node That Owns a Key)

import { Duration, Effect } from "effect";
import { RedisCluster } from "@effect-kit/redis";

export const nextJob = Effect.gen(function* () {
  const cluster = yield* RedisCluster;

  return yield* cluster.withBlockingSession({ key: "{jobs}:queue" }, (session) =>
    session.blpop(["{jobs}:queue"], { blockFor: Duration.seconds(1) }),
  );
});

A session checks every command against its node. A command for a different slot fails with ClusterError where reason is "cross-slot" or "session-route".

onPrimaries returns a lazy Stream of { node, result }, one per primary, in sequence. Each result is a Result, so one failed node does not stop the others. There is no atomicity and no retry.

TopologyCopy Anchor Link

cluster.topology returns the current ClusterTopology: a revision and a list of shards, each with its slots ranges, primary and replicas. The layer refreshes it every refreshIntervalMillis and after a redirect. cluster.refresh forces a refresh.

keySlot(key) computes the slot for a key. It applies hash tags, so keySlot("{user:42}:name") equals keySlot("{user:42}:visits").

OptionsCopy Anchor Link

Pass these as cluster next to url or endpoint. The connection and session options at the top level apply to every node.

A database other than 0 fails with ClusterError and reason: "database" unless databaseCapability is "valkey-multi-db", which Valkey 9.0 and later can be configured for.