Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Scaling and Adapters

Cluster and Alternative Adapters

Compare the Socket.IO adapters: in-memory, cluster, Redis Streams, Postgres, MongoDB and cloud queues, and pick one for recovery, cost and simplicity.

Redis pub/sub is not the only way to connect servers. Socket.IO has a small adapter interface, and several packages implement it on top of other systems. This lesson tours the options, shows what each is good at, and explains the one feature that depends on the choice: connection state recovery.

The adapter family

Adapter Transport between servers Typical use
In-memory (default) None, one process Development, single server
@socket.io/cluster-adapter Node.js cluster IPC Several workers on one machine
@socket.io/redis-adapter Redis pub/sub General purpose, most popular
@socket.io/redis-adapter (sharded) Redis 7 sharded pub/sub Redis Cluster
@socket.io/redis-streams-adapter Redis Streams Needs delivery replay and state recovery
@socket.io/mongo-adapter MongoDB capped collection / change streams You already run MongoDB
@socket.io/postgres-adapter PostgreSQL LISTEN / NOTIFY You already run PostgreSQL
@socket.io/gcp-pubsub-adapter Google Cloud Pub/Sub Google Cloud deployments
@socket.io/aws-sqs-adapter Amazon SNS + SQS AWS deployments
@socket.io/azure-service-bus-adapter Azure Service Bus Azure deployments

Package names and options change between releases, so check each package's README when you install it. The idea is always the same: take the adapter's recipe, call io.adapter(...), keep the rest of your code unchanged.

Cluster adapter: one machine, several workers

If you run one worker per CPU core with Node's cluster module, you do not need an external service at all. The cluster adapter sends broadcasts between workers through the primary process:

JavaScript
import cluster from "node:cluster";
import { createServer } from "node:http";
import { availableParallelism } from "node:os";
import { Server } from "socket.io";
import { createAdapter, setupPrimary } from "@socket.io/cluster-adapter";
import { setupMaster, setupWorker } from "@socket.io/sticky";

if (cluster.isPrimary) {
  const httpServer = createServer();
  setupMaster(httpServer, { loadBalancingMethod: "least-connection" });
  setupPrimary();
  httpServer.listen(3000);
  for (let i = 0; i < availableParallelism(); i++) cluster.fork();
  cluster.on("exit", () => cluster.fork()); // replace a crashed worker
} else {
  const httpServer = createServer();
  const io = new Server(httpServer);
  io.adapter(createAdapter());
  setupWorker(io);
  io.on("connection", (socket) => socket.on("ping-me", (cb) => cb({ pid: process.pid })));
}

This gives you multi-core use with zero infrastructure. It does not span machines. To use several machines, combine it with Redis or another cross-host adapter at the machine level, or run one process per container behind a load balancer and use Redis.

Node.js Workers talking through a primary (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Redis Streams adapter

Plain pub/sub is fire-and-forget: a server that is not subscribed at the moment of the message never sees it. Redis Streams keeps messages in a stream for a while and lets each consumer read from a known offset. The Streams adapter uses that to support connection state recovery across servers: a client that reconnects to a different node can be given the events it missed.

JavaScript
import { createClient } from "redis";
import { createAdapter } from "@socket.io/redis-streams-adapter";
import { Server } from "socket.io";

const redisClient = createClient({ url: "redis://localhost:6379" });
await redisClient.connect();

const io = new Server({
  adapter: createAdapter(redisClient),
  connectionStateRecovery: {
    maxDisconnectionDuration: 2 * 60 * 1000, // two minutes
    skipMiddlewares: true,
  },
});

The classic Redis adapter, Postgres, MongoDB and cluster adapters are different in this respect: with connection state recovery they only help when a client returns to the same node that kept its session buffer. Check the feature table of the adapter you choose.

Node.js Why a stream allows replay (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Postgres and MongoDB adapters

If you already operate PostgreSQL or MongoDB and want to avoid a new component, their adapters turn the database into the relay. The Postgres adapter uses LISTEN and NOTIFY (with a table for payloads larger than the roughly 8 KB notification limit). The MongoDB adapter uses a capped collection that every server tails.

JavaScript
import { Pool } from "pg";
import { createAdapter } from "@socket.io/postgres-adapter";
import { Server } from "socket.io";

const pool = new Pool({ host: "localhost", user: "app", password: process.env.PGPASSWORD, database: "app" });

await pool.query(`
  CREATE TABLE IF NOT EXISTS socket_io_attachments (
    id bigserial UNIQUE,
    created_at timestamptz DEFAULT NOW(),
    payload bytea
  )`);

const io = new Server({ adapter: createAdapter(pool) });

These are fine for modest traffic. A database is not built for thousands of tiny messages per second, so for high-volume apps Redis is usually the better relay.

Choosing an adapter

Pick by situation

One machine Cluster adapter plus sticky.
Already run Redis Redis adapter.
Only a database Postgres or Mongo adapter.
Cloud native SQS, Pub/Sub or Service Bus.

Need recovery across nodes? Redis Streams.

1 / 2
Node.js An adapter picker (decision stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Writing your own?

The adapter interface (broadcast, addAll, del, fetchSockets, serverSideEmit and friends) is documented, and the existing adapters extend a base class called ClusterAdapterWithHeartbeat, which handles the plumbing of node discovery and acknowledgements. You only implement "publish a message" and "receive a message" for your transport. That is how the cloud adapters were built, and it is a manageable job if you need a relay that does not exist yet.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which adapter is the natural choice for several Node.js workers on one machine without external services?

    The cluster adapter relays broadcasts through the primary process using IPC, so no external service is needed.
  2. 2. Why does the Redis Streams adapter support connection state recovery across servers?

    Missed events remain in the stream, so a node can replay everything after the offset the returning client reports.
  3. 3. What is a limit of the Postgres adapter?

    LISTEN/NOTIFY and a payload table are fine for moderate traffic but do not match the throughput of a dedicated message broker.

Summary

  • Adapters share one interface: pick the relay (IPC, Redis, Streams, Postgres, Mongo, cloud queues) and call io.adapter(...).
  • The cluster adapter plus sticky routing covers multi-core on one machine.
  • The Streams adapter keeps events for replay, which enables recovery on a different node.
  • Use an existing database adapter for modest traffic, Redis for high volume.
  • Whatever adapter you choose, you still need sticky sessions for polling.

Next: Acknowledgements and Timeouts