solid_queue_guard

Production readiness checks and runtime guards for Rails Solid Queue.

Rails 8 ships with Solid Queue. Redis is optional. Production config is not.

Your web tier can be green while your jobs are dead. Your queue can look empty while scheduled work is stuck. Your queue.yml can declare 10 threads against a database pool of 5.

solid_queue_guard catches that before it becomes a 3am incident.

Mission Control shows what is happening.
solid_queue_guard warns what is dangerous.

Why this exists

Solid Queue is excellent. Operating it blindly is not.

Symptom	What actually happened
"Site is up, emails stopped"	Workers dead, heartbeats stale
"Only 3 jobs in the queue, why the panic?"	Oldest job waiting 40 minutes — lag, not depth
"Recurring billing just… stopped"	Scheduler not running, nobody noticed for a week
"Jobs hang after deploy"	Thread count > DB pool — connection starvation
"Health check passes, jobs don't"	`/up` doesn't know Solid Queue exists

You don't need another dashboard. You need a doctor.

See it in action

bundle add solid_queue_guard
bin/rails solid_queue_guard:install
bin/rails solid_queue_guard:doctor

SolidQueueGuard Report

Status: DEGRADED

Checks:
✅ Active Job adapter is :solid_queue
✅ Queue database configured in database.yml
✅ Solid Queue connects_to queue database (pool: 10)
✅ Solid Queue schema tables present
❌ Worker threads: 10, queue DB pool: 5
⚠️ No workers configured for "mailers" queue
⚠️ recurring.yml exists but scheduler may not run
✅ Solid Queue is not co-located with Puma

Suggested fixes:
- Increase queue DB pool to at least 12 or reduce worker threads
- Add a worker for the mailers queue
- Verify scheduler process is running in production

One command. Actionable output. No Datadog required to get started.

What it checks

Configuration doctor

Runs locally, in CI, or pre-deploy. No extra infrastructure.

Check	Catches
Adapter	Active Job not set to `:solid_queue`
Queue database	Missing `queue` entry in `database.yml`
connects_to	Solid Queue pointing at the wrong DB / pool
Queue schema	Missing Solid Queue tables in schema files or queue database
Thread pool	`threads` > available queue DB connections
Worker coverage	Queues with no worker assigned
Scheduler	`recurring.yml` tasks without a scheduler
Env flags	`SOLID_QUEUE_SKIP_RECURRING=true` in production
Heartbeats	Default thresholds that may not fit your deploy
Puma plugin	Solid Queue co-located with web in production
Async supervisor	`async` mode with thread/pool sizing risks
Topology	`queue.yml` worker and pool recommendations

Runtime guards

Check	Catches
Queue lag	Oldest ready job waiting too long
Stale processes	Dead workers, dispatchers, schedulers
Dispatcher health	Scheduled jobs never becoming ready
Blocked jobs	Concurrency control silently holding jobs
Recurring staleness	Cron tasks that stopped firing
Puma plugin runtime	Plugin enabled but no active Solid Queue processes
HTTP `/health`	Kamal, ECS, K8s, UptimeRobot integration

Quick start

Install

bundle add solid_queue_guard
bin/rails solid_queue_guard:install
bin/rails generate solid_queue_guard:install:ci   # optional GitHub Actions workflow

Run the doctor

# Human-readable report
bin/rails solid_queue_guard:doctor

# JSON for scripts / CI
bin/rails "solid_queue_guard:doctor[json]"
SOLID_QUEUE_GUARD_FORMAT=json bin/rails solid_queue_guard:doctor

# Fail CI on warnings too
SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor

# Full report (config + runtime when available)
bin/rails solid_queue_guard:report

Exit codes

Code	Meaning
`0`	Healthy or degraded
`1`	Unhealthy (or degraded in `--strict` / `SOLID_QUEUE_GUARD_STRICT=1`)

Perfect for deploy pipelines:

# GitHub Actions
- name: Solid Queue production readiness
  run: SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor

Or generate a workflow:

bin/rails generate solid_queue_guard:install:ci

HTTP health

# config/routes.rb
mount SolidQueueGuard::Engine, at: "/solid_queue_guard"

curl localhost:3000/solid_queue_guard/health
# => { "status": "degraded", "queue_lag_seconds": 245, "warnings": [...] }

Optional token protection:

config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
# curl -H "X-Solid-Queue-Guard-Token: $TOKEN" ...

HTTP status policy (for Kamal, ECS, load balancers):

config.degraded_http_status = 207   # or :ok (200), 503, etc.
config.unhealthy_http_status = 503  # default

Works with Kamal, Heroku, Fly.io, ECS/Fargate, Kubernetes, Better Stack, UptimeRobot.

How to use it

Solid Queue does not show up in Rails /up. solid_queue_guard gives you three operational surfaces:

Surface	Command / URL	Best for
Doctor	`bin/rails solid_queue_guard:doctor`	Local pre-deploy, config review
CI gate	`SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor`	Block merges with broken queue config
HTTP health	`GET /solid_queue_guard/health`	Production uptime monitors (Kamal, ECS, UptimeRobot)

Mission Control shows what is happening. solid_queue_guard warns what is dangerous. Use both.

Local and pre-deploy

Run before changing queue.yml, database.yml, or recurring tasks:

bin/rails solid_queue_guard:doctor      # config checks (default scope)
bin/rails solid_queue_guard:report      # config + runtime when the queue DB is available

By default the install generator sets config.enabled = Rails.env.production?, so in development checks are skipped unless you enable them:

SolidQueueGuard.configure { |c| c.enabled = true }

Or run with production config locally when validating deploy readiness.

CI pipelines

Validate configuration before deploy. Process/runtime checks usually skip in CI because there is no bin/jobs supervisor on the runner.

- name: Solid Queue production readiness
  run: SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor

STRICT=1 turns warnings into exit code 1, so the pipeline fails on misconfigured pools, missing worker coverage, or missing schema tables — not only hard failures.

Generate a starter workflow:

bin/rails generate solid_queue_guard:install:ci

Production monitoring

Mount the engine and point your load balancer or Kamal health check at /solid_queue_guard/health:

# config/routes.rb
mount SolidQueueGuard::Engine, at: "/solid_queue_guard"

Runtime checks matter here: queue lag, stale heartbeats, dispatcher health, and process topology reflect live Solid Queue state.

Optional hardening:

config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
config.health_cache_ttl = 15.seconds
config.degraded_http_status = 207   # or :ok (200), 503, etc.
config.notify_with = [:rails_logger, :slack]

Typical flow

Developer          CI                    Production
    │               │                         │
    │ doctor        │ doctor --strict           │ GET /health (every 30–60s)
    ▼               ▼                         ▼
 "pool wrong?"   block bad deploy          alert: worker dead
 "schema ok?"    before merge              alert: queue lag

Runtime process checks

Runtime checks query the queue database (via SolidQueue::Record). If connects_to is missing or the DB is unreachable, they skip — they do not pass silently as healthy.

`process_topology` — are the expected roles present?

Reads distinct kind values from solid_queue_processes:

Kind	Role
`Supervisor`	Parent process (`bin/jobs`)
`Worker`	Consumes ready jobs
`Dispatcher`	Moves scheduled jobs to ready
`Scheduler`	Runs recurring tasks

Result	Meaning
⚠️ No processes	Nothing registered — supervisor not running
⚠️ No Worker	Jobs will not be processed
⚠️ No Dispatcher	Scheduled work may stall (when recurring/scheduled jobs exist)
✅ Pass	Expected kinds are present

This check looks at presence of records, not heartbeat freshness.

`stale_process` — are heartbeats fresh?

Finds processes where last_heartbeat_at is older than stale_process_threshold (default 5 minutes):

Result	Meaning
✅ Pass	All processes reported recently
❌ Fail	One or more workers/dispatchers look dead or stuck

Use this in production health to catch workers that died after deploy.

`pidfile` — optional supervisor liveness

When tmp/pids/solid_queue.pid (or SOLID_QUEUE_PIDFILE) exists, verifies the PID is alive. Often warns in development where bin/jobs is not running. Disable if you do not use pidfiles:

config.disabled_checks = [:pidfile]

`puma_plugin_runtime` — Solid Queue inside Puma

When plugin :solid_queue is in config/puma.rb, verifies active processes with recent heartbeats exist. Skips when the Puma plugin is not enabled.

Queue schema detection

QueueSchemaCheck does not require db/queue_schema.rb. It validates that all tables for your installed solid_queue version exist in any of:

db/queue_schema.rb
db/schema.rb
db/structure.sql
the connected queue database

Apps that keep Solid Queue tables only in structure.sql (common in Revelo-style repos) pass correctly.

Where each check type applies

Context	Config checks	Process / runtime checks
Local `doctor`	✅ Primary value	⚠️ Partial without `bin/jobs`
CI `--strict`	✅ Primary value	⏭️ Usually skip
Production `/health`	✅ When DB up	✅ Primary value

Configuration

# config/initializers/solid_queue_guard.rb
SolidQueueGuard.configure do |config|
  config.enabled = Rails.env.production?

  config.queue_lag_thresholds = {
    critical: 30.seconds,
    default:  5.minutes,
    mailers:  15.minutes
  }

  config.failed_jobs_threshold = 20
  config.stale_process_threshold = 5.minutes

  # Per-check overrides (v0.6+)
  config.disabled_checks = [:pidfile]
  config.checks.queue_lag = { threshold: 10.minutes }
  config.checks.failed_jobs = { threshold: 5, enabled: true }

  # HTTP status policy (v0.8+)
  # config.degraded_http_status = 207
  # config.unhealthy_http_status = 503

  # config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
  # config.integrate_rails_health = true
  # config.notify_with = [:rails_logger, :slack, :datadog, :webhook]
  # config.metrics_backends = [:statsd, :prometheus, :opentelemetry]
end

Public API (v1.0+)

The following surface is stable until 2.0 and follows semantic versioning:

API	Description
`SolidQueueGuard.configure`	Block-style configuration
`SolidQueueGuard.config`	Current configuration object
`SolidQueueGuard.enabled?`	Whether checks run
`solid_queue_guard:doctor`	Config readiness report
`solid_queue_guard:health`	Runtime health report
`solid_queue_guard:report`	Full diagnostic report
`solid_queue_guard:install`	Initializer generator
`solid_queue_guard:install:ci`	GitHub Actions workflow generator
`mount SolidQueueGuard::Engine`	HTTP health endpoint

Configuration attributes, rake tasks, and health JSON shape are public. Internal check classes and registry are @api private.

Breaking changes ship only in major versions (2.0+). Deprecations warn one minor version ahead.