ioredis

ioredis é o cliente Redis padrão para Node.js: suporte standalone, Sentinel e Cluster com APIs compatíveis com TypeScript.

Receita

Cartão de referência rápida - pronto para copiar e colar.

import Redis from "ioredis";
 
export const redis = new Redis(process.env.REDIS_URL!, {
  maxRetriesPerRequest: 3,
  enableReadyCheck: true,
  lazyConnect: false,
});
 
redis.on("error", (err) => {
  console.error({ msg: "redis_error", err: err.message });
});
 
export async function cacheGet(key: string) {
  return redis.get(key);
}

Quando usar isso:

• Cache compartilhado, armazenamento de sessão, limites de taxa ou backend BullMQ
• Você precisa de pipelines, scripts Lua ou Redis Cluster
• Redis gerenciado (ElastiCache, Upstash, Redis Cloud) com URLs TLS

Exemplo de Trabalho

// src/redis.ts
import Redis from "ioredis";
 
function createRedis() {
  const url = process.env.REDIS_URL!;
  if (process.env.REDIS_CLUSTER === "true") {
    return new Redis.Cluster([{ host: process.env.REDIS_HOST!, port: 6379 }], {
      redisOptions: { password: process.env.REDIS_PASSWORD },
    });
  }
  return new Redis(url, { maxRetriesPerRequest: 3 });
}
 
export const redis = createRedis();
 
// src/cache/batch.ts
export async function mgetJson<T>(keys: string[]): Promise<(T | null)[]> {
  if (keys.length === 0) return [];
  const pipeline = redis.pipeline();
  keys.forEach((k) => pipeline.get(k));
  const results = await pipeline.exec();
  return (results ?? []).map(([err, val]) => {
    if (err || val == null) return null;
    return JSON.parse(val as string) as T;
  });
}
 
// Desligamento gracioso
process.on("SIGTERM", async () => {
  await redis.quit();
});

O que isso demonstra:

• Fábrica para standalone vs Cluster
• Pipeline para multi-get sem N viagens de ida e volta
• quit() no desligamento para fechar a conexão de forma limpa

Mergulho Profundo

Opções de Conexão

Pipelines vs Multi

const pipe = redis.pipeline();
pipe.set("a", "1");
pipe.incr("counter");
await pipe.exec();
 
await redis.mset("a", "1", "b", "2");

• Pipeline: agrupa comandos, uma viagem de ida e volta pela rede
• Transações MULTI/EXEC: atômicas quando todas as chaves estão no mesmo slot (ressalva do Cluster)

Scripts Lua

const script = `
  local current = redis.call('GET', KEYS[1])
  if current == false then
    redis.call('SET', KEYS[1], ARGV[1], 'EX', ARGV[2])
    return 1
  end
  return 0
`;
await redis.eval(script, 1, "lock:job", "token", "30");

• Compare-and-set atômico para locks e limites de taxa
• Defina scripts uma vez; use SHA em produção para eficiência

Plugin Fastify

import fp from "fastify-plugin";
import { redis } from "./redis";
 
export const redisPlugin = fp(async (fastify) => {
  fastify.decorate("redis", redis);
  fastify.addHook("onClose", async () => {
    await redis.quit();
  });
});

Nota sobre BullMQ

• BullMQ usa ioredis internamente
• Workers frequentemente precisam de maxRetriesPerRequest: null em comandos bloqueantes - instâncias de cliente separadas para BullMQ vs cache do aplicativo

Armadilhas

• Novo Redis por requisição - esgotamento de soquetes. Correção: exportar singleton.
• Lotes de pipeline enormes - picos de memória. Correção: dividir pipelines em blocos (500-1000 ops).
• Multi-chave entre slots do Cluster - erros CROSSSLOT. Correção: hash tags {tenant}:key ou chaves separadas.
• Sem manipulador de erros - eventos error não tratados travam o Node. Correção: redis.on("error", ...).
• Usar Redis como banco de dados principal - persistência/AOF não substituem um SQL. Correção: cache + Postgres como fonte da verdade.

Alternativas

FAQs

Relacionados

• Noções Básicas de Cache - padrões cache-aside
• Armazenamentos de Sessão - express-session + Redis
• Locks Distribuídos - ressalvas do Redlock
• BullMQ - backend de fila
• Melhores Práticas de Cache - política de invalidação

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.