Saltar al contenido

Cola de trabajos en Postgres: saca los correos del request

En la práctica/ 16 min de lectura

Una tabla jobs, un worker en Node que toma filas con FOR UPDATE SKIP LOCKED, reintentos con espera exponencial y recuperación de trabajos colgados. Probado en PGlite.

  • Bases de datos
  • Node.js
En este artículo (8)
  1. El costo de hacer tareas pesadas dentro del request
  2. La tabla de trabajos en Postgres
  3. El worker de la cola con FOR UPDATE SKIP LOCKED
  4. Reintentos y trabajos fallidos
  5. Cuándo sí conviene una herramienta dedicada
  6. Errores comunes
  7. Preguntas frecuentes
  8. Checklist

Para sacar el envío de correos del request, guarda el trabajo en una tabla jobs de Postgres y responde de inmediato. Un proceso aparte, el worker, toma cada trabajo con FOR UPDATE SKIP LOCKED, lo ejecuta y lo marca como hecho o lo reintenta más tarde. Es una cola de trabajos sin servicios nuevos.

Aquí tienes la tabla, el worker en Node con Postgres.js, los reintentos y la recuperación de trabajos colgados, con las pruebas que ejecutamos contra PGlite (PostgreSQL 18.6 compilado a WebAssembly). El bloqueo con FOR UPDATE ya lo vimos en cómo evitar la sobreventa de inventario; aquí le sumamos SKIP LOCKED.

El costo de hacer tareas pesadas dentro del request

Cuando un cliente paga, tu endpoint crea el pedido y manda un correo de confirmación. Si el correo sale dentro del mismo request, el cliente espera al proveedor de correo, y eso trae cuatro problemas:

  • Latencia. En nuestra demo, con un envío falso de 300 ms, el pedido respondió en 307 ms; encolando el correo, en 2 a 4 ms. Es una prueba local: tu red dará otros números, pero el request deja de esperar.
  • Fallos acoplados. Si el proveedor está caído, falla el pedido; y si atrapas el error, el correo se pierde sin rastro.
  • Sin reintentos. Un error temporal, como un 421 del servidor SMTP, debería reintentarse en un minuto.
  • Timeouts de quien te llama. Según la documentación de webhooks HTTPS de Shopify, Shopify da un segundo para conectar y cinco para la petición completa, y sin respuesta reintenta 8 veces en 4 horas. La misma página recomienda una cola para responder dentro de esos cinco segundos.

Lanzar el envío sin await tampoco sirve: la promesa vive en la memoria del proceso y se pierde, sin registro, con un reinicio o un despliegue. La alternativa es que el request solo guarde lo que hay que hacer. Estas son las dos versiones del mismo pedido, de demo.mjs:

const fakeEmail = () => new Promise((resolve) => setTimeout(resolve, 300));

async function placeOrderInline(email) {
  const [order] = await sql`INSERT INTO orders (email) VALUES (${email}) RETURNING id`;
  await fakeEmail(); // the request waits for the provider
  return order.id;
}

async function placeOrder(email) {
  return sql.begin(async (tx) => {
    const [order] = await tx`INSERT INTO orders (email) VALUES (${email}) RETURNING id`;
    await enqueue(tx, "order-confirmation", { orderId: order.id, email });
    return order.id;
  });
}
  1. fakeEmail simula al proveedor de correo: tarda 300 ms.
  2. placeOrderInline crea el pedido y espera al correo: el request dura lo que el envío, y si el envío falla, falla el pedido.
  3. placeOrder crea el pedido e inserta el trabajo con enqueue dentro de sql.begin. Los dos se confirman juntos o ninguno: nunca queda un correo pendiente de un pedido que no existe, y una de nuestras pruebas lo comprueba.
el mismo pedido, con el correo dentro y fuera del requestantes · el request manda el correorequestINSERTsendEmail() · 300 ms201si el proveedor falla o tarda, falla o tarda el pedidodespués · el request encola y responderequestINSERT pedido + INSERT jobs201 en 2–4 msworkerclaimJob()sendEmail()doneotro proceso; si falla, se reintentael cliente ya no espera al proveedor de correomedido con PGlite local y un envío falso de 300 ms: 307 ms contra 2–4 ms

Desliza la figura para verla completa

Con un webhook es igual: verifica, encola y responde 200, como explicamos en cómo verificar el HMAC de los webhooks de Shopify.

La tabla de trabajos en Postgres

Una cola en Postgres es una tabla en la que cada fila es un trabajo. Este es schema.sql, el mismo de las pruebas:

CREATE TABLE jobs (
  id           bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  type         text        NOT NULL,
  payload      jsonb       NOT NULL,
  status       text        NOT NULL DEFAULT 'pending'
               CHECK (status IN ('pending', 'running', 'done', 'failed')),
  attempts     int         NOT NULL DEFAULT 0,
  max_attempts int         NOT NULL DEFAULT 5,
  run_at       timestamptz NOT NULL DEFAULT now(),
  locked_at    timestamptz,
  last_error   text,
  created_at   timestamptz NOT NULL DEFAULT now(),
  updated_at   timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX jobs_pending_run_at ON jobs (run_at) WHERE status = 'pending';
  1. type dice qué hacer (order-confirmation) y payload lleva los datos en jsonb: el id del pedido y el correo, no el HTML.
  2. status solo acepta pending, running, done y failed, por el CHECK.
  3. attempts cuenta cuántas veces se tomó el trabajo; max_attempts pone el límite, 5 por defecto.
  4. run_at es desde cuándo puede correr: now() al encolar, una hora futura tras un fallo. locked_at guarda cuándo lo tomó un worker y last_error, el último error.
  5. El índice parcial jobs_pending_run_at solo incluye las filas en pending, ordenadas por run_at.

Los trabajos terminados se acumulan y los pendientes son pocos: es el caso de la documentación de índices parciales, cuyo ejemplo son pedidos sin facturar, pocos y muy consultados. La misma página avisa que el índice solo se usa si el WHERE de la consulta implica su condición, así que el worker debe pedir status = 'pending' tal cual. Con 20.000 filas y 50 pendientes, el EXPLAIN de la consulta del worker en PGlite mostró Index Scan using jobs_pending_run_at.

Encolar es un INSERT. Este es enqueue.mjs:

export async function enqueue(sql, type, payload) {
  const [job] = await sql`
    INSERT INTO jobs (type, payload)
    VALUES (${type}, ${sql.json(payload)})
    RETURNING id`;
  return job.id;
}
  1. sql puede ser el cliente de Postgres.js o el tx de una transacción: así el trabajo se confirma con el pedido.
  2. sql.json(payload) manda el objeto como JSON. Con JSON.stringify(payload), en nuestra prueba la columna jsonb guardó un string y payload->>'email' devolvió null.
  3. El resto de columnas toma su valor por defecto: el trabajo nace pending y listo. RETURNING id devuelve su id, que llega como texto porque es bigint.

El worker de la cola con FOR UPDATE SKIP LOCKED

El worker toma un trabajo, lo ejecuta y anota el resultado. Lo delicado es tomarlo: con varios workers, cada trabajo debe ir a uno solo. Esta es la función, al principio de worker.mjs:

export async function claimJob(sql) {
  const [job] = await sql`
    UPDATE jobs
    SET status = 'running', locked_at = now(), attempts = attempts + 1, updated_at = now()
    WHERE id = (
      SELECT id FROM jobs
      WHERE status = 'pending' AND run_at <= now()
      ORDER BY run_at
      LIMIT 1
      FOR UPDATE SKIP LOCKED
    )
    RETURNING *`;
  return job ?? null;
}
  1. El SELECT interno busca el trabajo pendiente más antiguo que ya puede correr y se queda con uno.
  2. FOR UPDATE bloquea esa fila hasta que termine la transacción; SKIP LOCKED hace que, si otra transacción ya la bloqueó, la salte y tome la siguiente en vez de esperar.
  3. El UPDATE externo la pasa a running, apunta locked_at y suma uno a attempts.
  4. RETURNING * devuelve la fila actualizada. Si no hay nada pendiente no se actualiza ninguna fila, y según la documentación de UPDATE eso no es un error: la función devuelve null.
  5. Es una sola sentencia y su propia transacción: el bloqueo dura lo que el UPDATE, no lo que el correo. Después, lo que aparta el trabajo de los demás es status = 'running'.

La cláusula de bloqueo de SELECT lo dice así: con SKIP LOCKED, las filas que no se pueden bloquear de inmediato se saltan. Y advierte que eso da una vista inconsistente de los datos: no sirve para trabajo general, pero sí para evitar la contención entre varios consumidores de una tabla tipo cola. Para el stock sería un error, como contamos en el artículo de sobreventa.

dos workers, dos trabajos distintos: SKIP LOCKED salta la fila tomadatabla jobs1pendingbloqueada por A2pendingbloqueada por B3pending4pending5pendingworker Allega primeroworker Btoma el 2, sin esperarsalta el 1SELECT id FROM jobs WHERE status = 'pending' AND run_at <= now()ORDER BY run_at LIMIT 1 FOR UPDATE SKIP LOCKEDsin SKIP LOCKED, B esperaría el COMMIT de Ala fila bloqueada se salta: vista inconsistente, válida para colas

Desliza la figura para verla completa

Sin SKIP LOCKED, según la documentación de bloqueo explícito, el SELECT FOR UPDATE que encuentra la fila bloqueada espera a que la otra transacción termine: nada se repite, pero los workers hacen fila. Y sin bloqueo, en dos sentencias, dos workers pueden leer el mismo id antes de que alguno lo marque.

Para correr el worker, start.mjs conecta, registra los handlers y entra en el bucle work:

import postgres from "postgres";
import { work, recoverStuck } from "./worker.mjs";

// Fake sender: replace it with your email provider's client.
async function sendOrderEmail({ orderId, email }) {
  await new Promise((resolve) => setTimeout(resolve, 300));
  console.log(`email sent to ${email} for order ${orderId}`);
}

const sql = postgres(process.env.DATABASE_URL, { max: 1 });
const handlers = { "order-confirmation": sendOrderEmail };

setInterval(() => recoverStuck(sql).catch(console.error), 60_000);
await work(sql, handlers);
  1. sendOrderEmail es el envío falso; aquí va el cliente de tu proveedor. handlers conecta cada type con su función.
  2. Una sola conexión (max: 1) basta para un bucle de worker.
  3. Cada minuto, recoverStuck rescata los trabajos colgados, y work toma y ejecuta trabajos sin parar.

En demo.mjs arrancamos PGlite con su servidor de sockets, lanzamos start.mjs como otro proceso de Node e hicimos tres pedidos: cada uno respondió en 2 a 4 ms, el worker imprimió los tres email sent to … y los tres trabajos quedaron en done con attempts en 1.

Qué prueban nuestras pruebas, y qué no

queue.test.mjs usa el corredor de pruebas de Node y PGlite en 127.0.0.1, con una conexión por worker, como procesos distintos. Esta es la parte de la salida de node --test --test-reporter=spec queue.test.mjs que toca la concurrencia:

sent 50 emails for 50 orders; per worker 13 / 13 / 10 / 14
✔ 4 workers in parallel: each of 50 jobs is processed exactly once (2141.5746ms)
naive claim: 200 emails for 50 orders
✔ control: a two-step claim (SELECT, then UPDATE) processes jobs more than once (411.4018ms)
no locking clause, PGlite: 50 emails for 50 orders
✔ PGlite limit: the same single UPDATE without FOR UPDATE SKIP LOCKED also passes here (125.0162ms)
B waited 318 ms and got job 1 (per the docs, SKIP LOCKED in real Postgres skips row 1 and returns job 2)
✔ PGlite limit: a second connection waits for an open transaction instead of skipping its row (357.4703ms)
  1. Cuatro bucles work en paralelo: 50 correos para 50 pedidos, repartidos entre los cuatro.
  2. La prueba de control toma el trabajo en dos sentencias, sin bloqueo: cada pedido recibe cuatro correos. Prueba que las sentencias de las cuatro conexiones sí se intercalan.
  3. La toma en una sentencia pero sin FOR UPDATE SKIP LOCKED también pasa en PGlite, y una segunda conexión espera a la transacción abierta en vez de saltar su fila.

Ese es el límite de estas pruebas. PGlite es una base de una sola conexión; su servidor de sockets multiplexa, y su README avisa que no todos los casos funcionan como en un Postgres normal. En su código vimos que ejecuta una consulta a la vez y, con una transacción abierta, solo atiende a esa conexión: dos transacciones nunca se solapan y SKIP LOCKED nunca tiene nada que saltar. Lo probado es que, con sentencias intercaladas, cada trabajo se procesa una sola vez y la toma en dos pasos no lo logra. Que SKIP LOCKED evita la espera entre transacciones simultáneas lo dice la documentación de PostgreSQL; no lo medimos.

Reintentos y trabajos fallidos

Después de tomar el trabajo, runOne lo ejecuta y anota cómo terminó. Este es el resto de worker.mjs, salvo recoverStuck:

export async function runOne(sql, handlers, { backoffSeconds = 30 } = {}) {
  const job = await claimJob(sql);
  if (!job) return null;
  try {
    const handler = handlers[job.type];
    if (!handler) throw new Error(`no handler for job type ${job.type}`);
    await handler(job.payload, job);
    await sql`
      UPDATE jobs SET status = 'done', locked_at = NULL, updated_at = now()
      WHERE id = ${job.id} AND attempts = ${job.attempts}`;
    return job;
  } catch (err) {
    const status = job.attempts >= job.max_attempts ? "failed" : "pending";
    const delay = backoffSeconds * 2 ** (job.attempts - 1);
    await sql`
      UPDATE jobs SET status = ${status}, locked_at = NULL, last_error = ${String(err?.message ?? err)},
        run_at = now() + make_interval(secs => ${delay}), updated_at = now()
      WHERE id = ${job.id} AND attempts = ${job.attempts}`;
    return job;
  }
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function work(sql, handlers, { idleMs = 1000, signal } = {}) {
  while (!signal?.aborted) {
    if (!(await runOne(sql, handlers))) await sleep(idleMs);
  }
}
  1. Si no hay trabajo, runOne devuelve null. Un type sin handler cuenta como un error más, en lugar de tumbar el worker.
  2. Si el handler termina, el trabajo pasa a done.
  3. Si falla, vuelve a pending o, si llegó a max_attempts, queda en failed, con el mensaje en last_error.
  4. La espera crece así: backoffSeconds * 2 ** (attempts - 1), desde 30 s, sumada a now() en run_at. Hasta esa hora, claimJob no lo ve.
  5. AND attempts = ${job.attempts} protege las dos escrituras finales: si otro worker tomó el trabajo mientras tanto, attempts cambió y el worker atrasado no pisa su resultado. work repite runOne y duerme un segundo con la cola vacía.

La prueba de reintentos usa un handler que siempre falla con SMTP 421: try again later, comprueba que claimJob no lo devuelve antes de tiempo y adelanta run_at para no esperar de verdad. Esto quedó en la tabla tras cada intento:

IntentoEstado despuésEspera hasta el siguiente
1pending30 s
2pending60 s
3pending120 s
4pending240 s
5failedNinguna: no se vuelve a tomar

Son unos siete minutos y medio en total. Si quieres más margen, sube max_attempts o backoffSeconds. Un trabajo en failed conserva su last_error; para reintentarlo, vuelve a ponerlo en pending con attempts = 0.

los estados de un trabajo y qué los cambiaestadocuándomarcas de tiempose tomapendingenqueue()run_at = now()sírunningclaimJob()locked_at = now()nodoneel handler terminalocked_at = NULLnopendingfalla, n < max_attemptsnow() + 30 s · 2^(n-1)al vencerfailedfalla, n = max_attempts—nuncapendingcolgado > 15 minlocked_at = NULLsíun fallo vuelve a la cola hasta agotar los intentosn = attempts · esperas probadas: 30, 60, 120 y 240 s, luego failed

Desliza la figura para verla completa

Trabajos colgados en running

Si el worker se cae después de tomar el trabajo (un reinicio, un despliegue), la fila se queda en running para siempre. Para eso está recoverStuck:

export async function recoverStuck(sql, minutes = 15) {
  return sql`
    UPDATE jobs
    SET status = CASE WHEN attempts >= max_attempts THEN 'failed' ELSE 'pending' END,
        locked_at = NULL, last_error = 'stuck in running, lock expired', updated_at = now()
    WHERE status = 'running' AND locked_at < now() - make_interval(mins => ${minutes})
    RETURNING id, status`;
}
  1. Busca trabajos en running tomados hace más de minutes minutos, 15 por defecto.
  2. Los devuelve a pending, o a failed si ya no les quedan intentos, para que un trabajo que tumba al worker no se repita sin fin.
  3. Anota el motivo en last_error y devuelve el id y el estado nuevo de cada uno.

Elige minutes mayor que tu trabajo más lento: si uno vivo pasa del límite, se ejecuta dos veces. Nuestra prueba lo provoca: A toma el trabajo y se cuelga, envejecemos su locked_at, recoverStuck lo libera y B lo termina. Cuando A despierta y falla, la guarda de attempts descarta su escritura y el trabajo queda en done con attempts en 2. Al quitar la guarda, la prueba falla: A devuelve a pending un trabajo hecho.

Y muestra la garantía real: cada trabajo corre al menos una vez, no exactamente una. Haz los handlers idempotentes: comprueba si ese pedido ya tiene su correo y, si tu proveedor acepta una clave de idempotencia, pásale una estable, como en cómo evitar cobros dobles con una clave de idempotencia.

Cuándo sí conviene una herramienta dedicada

La tabla y unas sesenta líneas de Node cubren lo básico. Para más, hay herramientas dedicadas. Esto dice cada una de sí misma:

HerramientaQué dice serDónde guarda los trabajos
pg-bossUna cola de trabajos para Node.js sobre PostgreSQL, apoyada en SKIP LOCKED, con prioridades, colas dead letter, reintentos con espera exponencial y cron.PostgreSQL 13 o superior (pide Node 22.12+)
Graphile WorkerUna cola de trabajos de alto rendimiento para PostgreSQL, escrita en Node.js, que arranca trabajos en milisegundos con LISTEN/NOTIFY.PostgreSQL
BullMQUna cola distribuida de trabajos y mensajes, rápida y robusta; su documentación habla de entrega «al menos una vez» y pide procesadores idempotentes.Redis o compatibles, y también PostgreSQL
Amazon SQSColas de mensajes totalmente administradas para microservicios, sistemas distribuidos y aplicaciones serverless.Servicio de AWS

Nuestra regla: empieza con la tabla si ya usas Postgres y tu volumen cabe en él. Cambia cuando necesites cron, prioridades, dependencias entre trabajos, un panel o sacar ese volumen de tu base principal. pg-boss y Graphile Worker siguen en Postgres y conservan la ventaja de encolar en la transacción del pedido; con Redis o SQS el trabajo vive fuera de tu base y esa garantía la construyes tú.

Errores comunes

  • Tomar el trabajo en dos pasos. Un SELECT y luego un UPDATE dejan un hueco: en nuestra prueba, 200 correos para 50 pedidos. Usa una sola sentencia con FOR UPDATE SKIP LOCKED.
  • Procesar con la transacción abierta. Si mandas el correo antes del COMMIT, la fila sigue bloqueada y la conexión ocupada durante todo el envío. Toma, confirma y procesa fuera.
  • Olvidar los trabajos colgados. Sin recoverStuck, un worker que se cae deja trabajos en running para siempre.
  • Esperar un orden estricto. La documentación de SELECT avisa que ORDER BY con una cláusula de bloqueo puede devolver filas fuera de orden en Read Committed, y SKIP LOCKED deja que un trabajo adelante a otro. El orden es aproximado.
  • Handlers que no son idempotentes. La cola garantiza al menos una ejecución: si el correo salió y el worker cayó antes de marcarlo, el reintento lo repite.
  • Dejar crecer la tabla. Nuestra recomendación: borra los done de más de unos días con un DELETE periódico, y revisa los failed antes de borrarlos.

Preguntas frecuentes

¿Tengo que consultar la tabla cada segundo?

Con el índice parcial, consultar una cola vacía cada segundo es barato. Para menos espera existe LISTEN/NOTIFY: según la documentación de NOTIFY, un aviso enviado en una transacción solo se entrega si se confirma, el contenido debe medir menos de 8000 bytes por defecto y solo lo reciben sesiones que ya hicieron LISTEN. Úsalo para despertar al worker y conserva la consulta periódica. No está en el código probado.

¿Cuántos workers pongo?

Empieza con uno o dos y vigila cuántos trabajos en pending tienen run_at vencido. Si ese número crece, agrega workers, sin olvidar que cada uno ocupa una conexión de tu Postgres.

¿Puedo programar un trabajo para más tarde?

Sí: inserta la fila con run_at futuro, por ejemplo now() + interval '1 hour'. claimJob la ignora hasta esa hora, igual que a un reintento en espera; la prueba de reintentos comprueba ese comportamiento.

¿Qué pasa si el worker se cae justo después de mandar el correo?

El trabajo queda en running; a los 15 minutos, recoverStuck lo devuelve a pending y otro worker lo repite. El cliente recibe dos correos salvo que el handler compruebe antes si ya lo envió.

Checklist

  • El request guarda el trabajo en la misma transacción que el pedido y responde.
  • La tabla tiene status con CHECK, attempts, max_attempts, run_at y locked_at, más un índice parcial sobre pending.
  • El worker toma cada trabajo en una sentencia: UPDATE … WHERE id = (SELECT … FOR UPDATE SKIP LOCKED) RETURNING *.
  • El correo se manda fuera de cualquier transacción.
  • Un fallo vuelve a pending con espera exponencial y acaba en failed tras max_attempts.
  • recoverStuck corre cada minuto con un límite mayor que el trabajo más lento.
  • Las escrituras finales llevan la guarda AND attempts = … y los handlers son idempotentes.
  • Los trabajos terminados se borran pasado un plazo.

Con la cola, el request hace lo mínimo y lo lento se reintenta solo. Empieza por tus webhooks: verifica el HMAC de los webhooks de Shopify, encola y responde. Si el trabajo toca stock, repasa cómo evitar la sobreventa de inventario; si cobra, cómo evitar cobros dobles.

¿Viste esto en Instagram? Comenta COLAS en el Reel y te mando la guía.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 3 de noviembre de 2026

← Blog