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)
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
421del 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;
});
}
fakeEmailsimula al proveedor de correo: tarda 300 ms.placeOrderInlinecrea el pedido y espera al correo: el request dura lo que el envío, y si el envío falla, falla el pedido.placeOrdercrea el pedido e inserta el trabajo conenqueuedentro desql.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.
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';
typedice qué hacer (order-confirmation) ypayloadlleva los datos enjsonb: el id del pedido y el correo, no el HTML.statussolo aceptapending,running,doneyfailed, por elCHECK.attemptscuenta cuántas veces se tomó el trabajo;max_attemptspone el límite, 5 por defecto.run_ates desde cuándo puede correr:now()al encolar, una hora futura tras un fallo.locked_atguarda cuándo lo tomó un worker ylast_error, el último error.- El índice parcial
jobs_pending_run_atsolo incluye las filas enpending, ordenadas porrun_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;
}
sqlpuede ser el cliente de Postgres.js o eltxde una transacción: así el trabajo se confirma con el pedido.sql.json(payload)manda el objeto como JSON. ConJSON.stringify(payload), en nuestra prueba la columnajsonbguardó un string ypayload->>'email'devolviónull.- El resto de columnas toma su valor por defecto: el trabajo nace
pendingy listo.RETURNING iddevuelve su id, que llega como texto porque esbigint.
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;
}
- El
SELECTinterno busca el trabajo pendiente más antiguo que ya puede correr y se queda con uno. FOR UPDATEbloquea esa fila hasta que termine la transacción;SKIP LOCKEDhace que, si otra transacción ya la bloqueó, la salte y tome la siguiente en vez de esperar.- El
UPDATEexterno la pasa arunning, apuntalocked_aty suma uno aattempts. 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 devuelvenull.- 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 esstatus = '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.
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);
sendOrderEmailes el envío falso; aquí va el cliente de tu proveedor.handlersconecta cadatypecon su función.- Una sola conexión (
max: 1) basta para un bucle de worker. - Cada minuto,
recoverStuckrescata los trabajos colgados, yworktoma 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)
- Cuatro bucles
worken paralelo: 50 correos para 50 pedidos, repartidos entre los cuatro. - 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.
- La toma en una sentencia pero sin
FOR UPDATE SKIP LOCKEDtambié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);
}
}
- Si no hay trabajo,
runOnedevuelvenull. Untypesin handler cuenta como un error más, en lugar de tumbar el worker. - Si el handler termina, el trabajo pasa a
done. - Si falla, vuelve a
pendingo, si llegó amax_attempts, queda enfailed, con el mensaje enlast_error. - La espera crece así:
backoffSeconds * 2 ** (attempts - 1), desde 30 s, sumada anow()enrun_at. Hasta esa hora,claimJobno lo ve. AND attempts = ${job.attempts}protege las dos escrituras finales: si otro worker tomó el trabajo mientras tanto,attemptscambió y el worker atrasado no pisa su resultado.workrepiterunOney 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:
| Intento | Estado después | Espera hasta el siguiente |
|---|---|---|
| 1 | pending | 30 s |
| 2 | pending | 60 s |
| 3 | pending | 120 s |
| 4 | pending | 240 s |
| 5 | failed | Ninguna: 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.
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`;
}
- Busca trabajos en
runningtomados hace más deminutesminutos, 15 por defecto. - Los devuelve a
pending, o afailedsi ya no les quedan intentos, para que un trabajo que tumba al worker no se repita sin fin. - Anota el motivo en
last_errory 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:
| Herramienta | Qué dice ser | Dónde guarda los trabajos |
|---|---|---|
| pg-boss | Una 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 Worker | Una cola de trabajos de alto rendimiento para PostgreSQL, escrita en Node.js, que arranca trabajos en milisegundos con LISTEN/NOTIFY. | PostgreSQL |
| BullMQ | Una 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 SQS | Colas 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
SELECTy luego unUPDATEdejan un hueco: en nuestra prueba, 200 correos para 50 pedidos. Usa una sola sentencia conFOR 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 enrunningpara siempre. - Esperar un orden estricto. La documentación de
SELECTavisa queORDER BYcon una cláusula de bloqueo puede devolver filas fuera de orden en Read Committed, ySKIP LOCKEDdeja 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
donede más de unos días con unDELETEperiódico, y revisa losfailedantes 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
statusconCHECK,attempts,max_attempts,run_atylocked_at, más un índice parcial sobrepending. - 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
pendingcon espera exponencial y acaba enfailedtrasmax_attempts. recoverStuckcorre 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

Publicado el 3 de noviembre de 2026