Run and Diagnose Background Jobs
Learn why enqueuing a job is not the same as running it, choose where the Solid Queue worker lives (in-Puma flag vs. dedicated container), and diagnose and fix the classic 'jobs queued but nothing runs' incident by counting live processes and drained executions.
PremiumEnqueue is not execute
In a Rails app, SomeJob.perform_later(...) does not run your code. It
writes a row to a queue and returns immediately. Something else — a worker
— has to pick that row up and actually execute it. If no worker is running,
the row just sits there. Forever.
This playbook uses Solid Queue, the database-backed Active Job backend
(its tables live in Postgres, often in a separate queue database). Because
the queue is just tables, it is easy to forget that inserting a row and
processing a row are two completely different things — and that the processing
side is a separate moving part you have to run and keep alive.
The failure this playbook trains you to handle is the classic one:
Welcome emails, embeddings/RAG indexing, notifications, reindex jobs — all
enqueue fine, the code has no errors, and nothing ever happens. The
backlog grows and the app looks healthy.
You will learn to tell "enqueued" from "executed", decide where the worker
runs, diagnose a dead-worker incident with three counters, fix it, and
verify the backlog drains — plus the trap of jobs that enqueue other jobs.