BullMQ

Q: Quantas filas?

Divida por domínio e SLO: email, webhooks, media. Evite uma fila gigante.

Q: NestJS BullMQ?

BullModule.registerQueue no módulo API; bootstrap de worker separado importa processadores.

Q: Desduplicação de jobs?

jobId estável em queue.add. Combine com chaves de idempotência no worker.

BullMQ é a biblioteca de filas com backend Redis que a maioria das equipes Node usa para e-mails, webhooks, processamento de mídia e sincronização em segundo plano.

Receita

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

import { Queue, Worker } from "bullmq";
import IORedis from "ioredis";
 
const connection = new IORedis(process.env.REDIS_URL!, { maxRetriesPerRequest: null });
 
export const reportQueue = new Queue("reports", { connection });
 
new Worker(
  "reports",
  async (job) => {
    await buildReport(job.data.reportId);
  },
  { connection: connection.duplicate(), concurrency: 3 }
);

Quando usar isso:

Você já executa Redis para cache ou sessões
Precisa de jobs atrasados, novas tentativas, prioridades e UI de observabilidade (Bull Board)
Workers Node em ECS/k8s separados da API

Exemplo de Trabalho

// src/queues/connection.ts
import IORedis from "ioredis";
 
export function createBullConnection() {
  return new IORedis(process.env.REDIS_URL!, {
    maxRetriesPerRequest: null,
    enableReadyCheck: false,
  });
}
 
// src/queues/reports.ts
import { Queue, Worker, QueueEvents } from "bullmq";
import { createBullConnection } from "./connection";
import { buildReport } from "../services/reports";
 
const connection = createBullConnection();
export const reportsQueue = new Queue("reports", { connection });
 
export function startReportWorker() {
  const worker = new Worker(
    "reports",
    async (job) => {
      await job.updateProgress(10);
      const url = await buildReport(job.data.reportId);
      await job.updateProgress(100);
      return { url };
    },
    {
      connection: createBullConnection(),
      concurrency: 2,
      lockDuration: 30_000,
    }
  );
 
  worker.on("failed", (job, err) => {
    console.error({ msg: "job_failed", jobId: job?.id, err: err.message });
  });
 
  worker.on("stalled", (jobId) => {
    console.warn({ msg: "job_stalled", jobId });
  });
 
  return worker;
}
 
// src/api/reports-route.ts
import express from "express";
import { reportsQueue } from "../queues/reports";
 
const router = express.Router();
 
router.post("/", async (req, res) => {
  const job = await reportsQueue.add(
    "build",
    { reportId: req.body.reportId },
    { attempts: 3, backoff: { type: "exponential", delay: 1000 } }
  );
  res.status(202).json({ jobId: job.id });
});
 
export default router;

O que isso demonstra:

Fábrica de conexão dedicada para os requisitos do BullMQ
Atualizações de progresso para UI de polling
Manipuladores failed e stalled para visibilidade de operações
Backoff exponencial em falhas de build transitórias

Mergulho Profundo

Jobs Paralisados

Falha do worker no meio do job deixa o lock até que lockDuration expire
BullMQ move o job de volta para aguardando - pode executar duas vezes
Workers idempotentes são obrigatórios, não opcionais

Desligamento Gracioso

const worker = startReportWorker();
 
process.on("SIGTERM", async () => {
  await worker.close(); // aguarda o job atual por padrão
  process.exit(0);
});

Emparelhe com terminationGracePeriodSeconds do k8s > duração mais longa do job
Pare de aceitar novas enfileiramentos HTTP durante a drenagem, se necessário

Jobs Repetíveis

await reportsQueue.add(
  "nightly",
  {},
  { repeat: { pattern: "0 2 * * *" }, jobId: "nightly-report" }
);

jobId evita definições repetíveis duplicadas na reimplantacão
Veja Agendamento e Cron

FlowProducer (Pai/Filho)

import { FlowProducer } from "bullmq";
 
const flow = new FlowProducer({ connection });
await flow.add({
  name: "invoice-pdf",
  queueName: "pdf",
  data: { invoiceId },
  children: [{ name: "fetch-line-items", queueName: "data", data: { invoiceId } }],
});

O pai executa após a conclusão dos filhos
Útil para pipeline sem encadear enfileiramento manual em cada worker

Bull Board (UI de Operações)

Monte @bull-board/express atrás de autenticação de administrador
Permite que o suporte inspecione jobs falhados e os reexecute manualmente

Armadilhas

Mesma conexão ioredis para Fila e Worker bloqueante - bugs sutis. Correção: duplicar conexões.
maxRetriesPerRequest padrão no worker - quebra o BRPOP. Correção: null nas conexões Bull.
Dados de job enormes no Redis - pressão de memória. Correção: ponteiro S3 no payload.
Sem monitoramento de paralisados - processamento duplicado silencioso. Correção: alertar sobre eventos stalled.
Novas tentativas infinitas - loops de mensagem venenosas para sempre. Correção: limitar tentativas + processo de revisão de DLQ.

Alternativas

Alternativa	Use Quando	Não Use Quando
AWS SQS	Sem operações Redis, nativo da AWS	Precisa de fluxos de jobs complexos sem orquestração adicional
pg-boss	Pilha apenas Postgres	Redis já é central
Temporal	Sagas de longa duração, tarefas humanas	Fila de e-mail simples
RabbitMQ	Existência corporativa AMQP	Equipe não tem apetite por operações Erlang

FAQs

BullMQ vs Bull v3?

BullMQ é o sucessor mantido com melhor TypeScript e desempenho. Novos projetos usam BullMQ.

Quantas filas?

Divida por domínio e SLO: email, webhooks, media. Evite uma fila gigante.

Concorrência por worker?

Comece com 2-5 jobs de I/O. Trabalho limitado por CPU: concorrência de 1 por núcleo após profiling.

Suporte ao Cluster Redis?

Suportado com prefixo e tags de hash por documento BullMQ. Teste failover.

NestJS BullMQ?

BullModule.registerQueue no módulo API; bootstrap de worker separado importa processadores.

Desduplicação de jobs?

jobId estável em queue.add. Combine com chaves de idempotência no worker.

Limitação de taxa de API de saída?

Opção de limitador de taxa BullMQ por fila protege cotas de fornecedores.

Testando workers?

Use Redis Testcontainer; afirme que o job foi concluído e o efeito colateral ocorreu uma vez.

Observabilidade?

Instrumentação OpenTelemetry bullmq + métricas de profundidade da fila (aguardando, ativo, atrasado).

Inversão de prioridade?

Alta prioridade inunda baixa - use filas separadas para SLAs escalonados em vez disso.

Relacionado

Noções Básicas de Filas - modelo mental
ioredis - cliente Redis
Chaves de Idempotência - novas tentativas seguras
Agendamento e Cron - jobs repetíveis
Melhores Práticas de Filas - alertas de profundidade

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

Receita

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

import { Queue, Worker } from "bullmq";
import IORedis from "ioredis";
 
const connection = new IORedis(process.env.REDIS_URL!, { maxRetriesPerRequest: null });
 
export const reportQueue = new Queue("reports", { connection });
 
new Worker(
  "reports",
  async (job) => {
    await buildReport(job.data.reportId);
  },
  { connection: connection.duplicate(), concurrency: 3 }
);

Quando usar isso:

Você já executa Redis para cache ou sessões
Precisa de jobs atrasados, novas tentativas, prioridades e UI de observabilidade (Bull Board)
Workers Node em ECS/k8s separados da API

Exemplo de Trabalho

// src/queues/connection.ts
import IORedis from "ioredis";
 
export function createBullConnection() {
  return new IORedis(process.env.REDIS_URL!, {
    maxRetriesPerRequest: null,
    enableReadyCheck: false,
  });
}
 
// src/queues/reports.ts
import { Queue, Worker, QueueEvents } from "bullmq";
import { createBullConnection } from "./connection";
import { buildReport } from "../services/reports";
 
const connection = createBullConnection();
export const reportsQueue = new Queue("reports", { connection });
 
export function startReportWorker() {
  const worker = new Worker(
    "reports",
    async (job) => {
      await job.updateProgress(10);
      const url = await buildReport(job.data.reportId);
      await job.updateProgress(100);
      return { url };
    },
    {
      connection: createBullConnection(),
      concurrency: 2,
      lockDuration: 30_000,
    }
  );
 
  worker.on("failed", (job, err) => {
    console.error({ msg: "job_failed", jobId: job?.id, err: err.message });
  });
 
  worker.on("stalled", (jobId) => {
    console.warn({ msg: "job_stalled", jobId });
  });
 
  return worker;
}
 
// src/api/reports-route.ts
import express from "express";
import { reportsQueue } from "../queues/reports";
 
const router = express.Router();
 
router.post("/", async (req, res) => {
  const job = await reportsQueue.add(
    "build",
    { reportId: req.body.reportId },
    { attempts: 3, backoff: { type: "exponential", delay: 1000 } }
  );
  res.status(202).json({ jobId: job.id });
});
 
export default router;

O que isso demonstra:

Fábrica de conexão dedicada para os requisitos do BullMQ
Atualizações de progresso para UI de polling
Manipuladores failed e stalled para visibilidade de operações
Backoff exponencial em falhas de build transitórias

Mergulho Profundo

Jobs Paralisados

Falha do worker no meio do job deixa o lock até que lockDuration expire
BullMQ move o job de volta para aguardando - pode executar duas vezes
Workers idempotentes são obrigatórios, não opcionais

Desligamento Gracioso

const worker = startReportWorker();
 
process.on("SIGTERM", async () => {
  await worker.close(); // aguarda o job atual por padrão
  process.exit(0);
});

Emparelhe com terminationGracePeriodSeconds do k8s > duração mais longa do job
Pare de aceitar novas enfileiramentos HTTP durante a drenagem, se necessário

Jobs Repetíveis

await reportsQueue.add(
  "nightly",
  {},
  { repeat: { pattern: "0 2 * * *" }, jobId: "nightly-report" }
);

jobId evita definições repetíveis duplicadas na reimplantacão
Veja Agendamento e Cron

FlowProducer (Pai/Filho)

import { FlowProducer } from "bullmq";
 
const flow = new FlowProducer({ connection });
await flow.add({
  name: "invoice-pdf",
  queueName: "pdf",
  data: { invoiceId },
  children: [{ name: "fetch-line-items", queueName: "data", data: { invoiceId } }],
});

O pai executa após a conclusão dos filhos
Útil para pipeline sem encadear enfileiramento manual em cada worker

Bull Board (UI de Operações)

Monte @bull-board/express atrás de autenticação de administrador
Permite que o suporte inspecione jobs falhados e os reexecute manualmente

Armadilhas

Mesma conexão ioredis para Fila e Worker bloqueante - bugs sutis. Correção: duplicar conexões.
maxRetriesPerRequest padrão no worker - quebra o BRPOP. Correção: null nas conexões Bull.
Dados de job enormes no Redis - pressão de memória. Correção: ponteiro S3 no payload.
Sem monitoramento de paralisados - processamento duplicado silencioso. Correção: alertar sobre eventos stalled.
Novas tentativas infinitas - loops de mensagem venenosas para sempre. Correção: limitar tentativas + processo de revisão de DLQ.

Alternativas

Alternativa	Use Quando	Não Use Quando
AWS SQS	Sem operações Redis, nativo da AWS	Precisa de fluxos de jobs complexos sem orquestração adicional
pg-boss	Pilha apenas Postgres	Redis já é central
Temporal	Sagas de longa duração, tarefas humanas	Fila de e-mail simples
RabbitMQ	Existência corporativa AMQP	Equipe não tem apetite por operações Erlang

FAQs

BullMQ vs Bull v3?

BullMQ é o sucessor mantido com melhor TypeScript e desempenho. Novos projetos usam BullMQ.

Quantas filas?

Divida por domínio e SLO: email, webhooks, media. Evite uma fila gigante.

Concorrência por worker?

Comece com 2-5 jobs de I/O. Trabalho limitado por CPU: concorrência de 1 por núcleo após profiling.

Suporte ao Cluster Redis?

Suportado com prefixo e tags de hash por documento BullMQ. Teste failover.

NestJS BullMQ?

BullModule.registerQueue no módulo API; bootstrap de worker separado importa processadores.

Desduplicação de jobs?

jobId estável em queue.add. Combine com chaves de idempotência no worker.

Limitação de taxa de API de saída?

Opção de limitador de taxa BullMQ por fila protege cotas de fornecedores.

Testando workers?

Use Redis Testcontainer; afirme que o job foi concluído e o efeito colateral ocorreu uma vez.

Observabilidade?

Instrumentação OpenTelemetry bullmq + métricas de profundidade da fila (aguardando, ativo, atrasado).

Inversão de prioridade?

Alta prioridade inunda baixa - use filas separadas para SLAs escalonados em vez disso.

Relacionado

Noções Básicas de Filas - modelo mental
ioredis - cliente Redis
Chaves de Idempotência - novas tentativas seguras
Agendamento e Cron - jobs repetíveis
Melhores Práticas de Filas - alertas de profundidade

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

BullMQ

Buscar na documentação

BullMQ