If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/rails/solid_queue shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 7w ago
• 22+ active contributors
• Distributed ownership (top contributor 39% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live rails/solid_queue repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rails/solid_queue.

What it runs against: a local clone of rails/solid_queue — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in rails/solid_queue | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 80 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rails/solid_queue. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rails/solid_queue.git
#   cd solid_queue
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of rails/solid_queue and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "rails/solid_queue(\\.git)?\\b" \\
  && ok "origin remote is rails/solid_queue" \\
  || miss "origin remote is not rails/solid_queue (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "lib/solid_queue.rb" \\
  && ok "lib/solid_queue.rb" \\
  || miss "missing critical file: lib/solid_queue.rb"
test -f "lib/active_job/queue_adapters/solid_queue_adapter.rb" \\
  && ok "lib/active_job/queue_adapters/solid_queue_adapter.rb" \\
  || miss "missing critical file: lib/active_job/queue_adapters/solid_queue_adapter.rb"
test -f "app/models/solid_queue/job.rb" \\
  && ok "app/models/solid_queue/job.rb" \\
  || miss "missing critical file: app/models/solid_queue/job.rb"
test -f "lib/solid_queue/dispatcher.rb" \\
  && ok "lib/solid_queue/dispatcher.rb" \\
  || miss "missing critical file: lib/solid_queue/dispatcher.rb"
test -f "lib/solid_queue/processes/poller.rb" \\
  && ok "lib/solid_queue/processes/poller.rb" \\
  || miss "missing critical file: lib/solid_queue/processes/poller.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 80 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~50d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/rails/solid_queue"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Solid Queue is a database-backed Active Job backend for Ruby on Rails that replaces the default queuing system with a SQL-based implementation. It stores job metadata (executions, schedules, recurring tasks) directly in the database, supporting delayed jobs, concurrency controls, recurring tasks, queue pausing, job priorities, and bulk enqueuing—while leveraging FOR UPDATE SKIP LOCKED for efficient lock-free polling on MySQL/PostgreSQL/SQLite. Modular Rails engine structure: app/models/solid_queue/ contains core domain objects (Execution, Job, RecurringTask, Process, Queue, Semaphore); app/models/solid_queue/execution/ and app/models/solid_queue/job/ use mixins for concerns (Dispatching, Retryable, Schedulable, Concurrency Controls); app/jobs/solid_queue/ contains recurring job handler; config/queue.yml and config/recurring.yml configure queue behavior and scheduled tasks.

Rails developers building production applications who need a reliable, database-native job queue without external dependencies like Redis. Specifically: teams running Rails 7.1+ who want the simplicity of SQL-backed storage, visibility into job state via their existing database, and advanced features like concurrency controls and recurring task scheduling.

Actively maintained and production-ready. The codebase is substantial (~308KB Ruby), includes comprehensive test coverage (inferred from test directory presence), has CI/CD via GitHub Actions (.github/workflows/main.yml), and is part of official Rails 8 defaults. Commit recency and Rails 8 integration indicate active development with stable API.

Low risk for Rails-native adoption, but database-dependent: all job state lives in SQL, so database performance/availability directly impacts job processing; schema migrations required during upgrades (see UPGRADING.md). Single-database bottleneck possible at scale if not tuned via FOR UPDATE SKIP LOCKED support. Dependency on Active Job internals means Rails version constraints matter (minimum 7.1).

Actively developed as part of Rails 8 launch; repository shows stable feature set with focus on reliability. Recent work likely targets performance tuning (FOR UPDATE SKIP LOCKED optimization), Rails version compatibility (Appraisals lists rails_7_1.gemfile), and internal refinements. No visible major breaking changes—focus is on production hardening.

git clone https://github.com/rails/solid_queue.git
cd solid_queue
bundle install
bin/setup
bundle exec rake test

Note: requires Ruby 3.1.6+ and Rails 7.1+; uses Bundler for dependency management.

Daily commands: Development mode via bin/setup installs dependencies. To use locally: bundle exec rails solid_queue:install in a Rails app, then bin/jobs start (generated by installer) or configure via config/queue.yml. Tests: bundle exec rake test. Docker available via .devcontainer/Dockerfile for containerized development.

• lib/solid_queue.rb — Primary entry point and configuration loader for the entire Solid Queue system.
• lib/active_job/queue_adapters/solid_queue_adapter.rb — Active Job adapter that bridges Rails job enqueueing to Solid Queue's database backend.
• app/models/solid_queue/job.rb — Core Job model representing queued work items; all execution states depend on this.
• lib/solid_queue/dispatcher.rb — Dispatcher process that enqueues scheduled/delayed jobs and manages job lifecycle transitions.
• lib/solid_queue/processes/poller.rb — Poller process that claims and executes ready jobs from the database using FOR UPDATE SKIP LOCKED.
• app/models/solid_queue/execution.rb — Execution state machine tracking job attempts, blocking, scheduling, and failure paths.
• lib/solid_queue/cli.rb — Command-line interface for starting supervisor, dispatcher, and worker processes.

Add a new queue with custom configuration

1. Define queue in config/solid_queue.yml under the queues section with desired concurrency and polling interval (config/solid_queue.yml)
2. Enqueue jobs to that queue by setting the queue option in your Active Job: MyJob.set(queue: 'my_queue').perform_later (lib/active_job/queue_adapters/solid_queue_adapter.rb)

Add a recurring job

1. Create a job class inheriting from ApplicationJob with SolidQueue::RecurringJob mixin (app/jobs/solid_queue/recurring_job.rb)
2. Define the task in config/solid_queue/recurring.yml with class name, schedule (cron), and arguments (config/solid_queue.yml)
3. Scheduler process will automatically create and enqueue recurring executions based on cron schedule (lib/solid_queue/scheduler.rb)

Add concurrency control to a job

1. Include ActiveJob::ConcurrencyControls in your job class and declare concurrency_controls with key and limit (lib/active_job/concurrency_controls.rb)
2. When job is enqueued, Solid Queue checks the concurrency limit and creates blocked_execution if limit reached (app/models/solid_queue/job/concurrency_controls.rb)
3. Dispatcher's concurrency_maintenance evaluates blocked executions and releases them when permits available (lib/solid_queue/dispatcher/concurrency_maintenance.rb)

Pause/resume a queue

1. Create a Pause record with queue_name to halt processing on that queue (app/models/solid_queue/pause.rb)
2. Poller checks for active pauses before claiming jobs from a queue (lib/solid_queue/processes/poller.rb)
3. Delete the Pause record to resume queue processing (app/models/solid_queue/pause.rb)

• ActiveRecord ORM — Single abstraction for Job, Execution, Queue state across MySQL, PostgreSQL, SQLite without custom SQL dialects
• FOR UPDATE SKIP LOCKED SQL clause — Lock-free job claiming with high throughput; skips already-locked rows to avoid contention and blocking
• Database as source of truth — Eliminates separate Redis/cache system; simpler deployment, persistence, and recovery from process crashes
• Cron scheduling (Fugit library) — Industry-standard schedule syntax for recurring jobs; no separate task scheduler dependency
• Process forking + threading hybrid — Separate supervisor, dispatcher, and worker processes for isolation; thread pools within pollers for concurrency

• Database-backed queuing instead of Redis

  • Why: Reduces infrastructure; uses existing Rails database
  • Consequence: Slightly higher per-job latency (~10–100ms polling intervals); disk I/O overhead vs. in-memory; acceptable for most non-realtime workloads

• Polling-based job claiming vs. event/listener model

  • Why: Works across all SQL databases without triggers or LISTEN/NOTIFY; simple, predictable behavior
  • Consequence: Configurable polling interval introduces job pickup latency; requires tuning for performance trade-offs

• Separate Dispatcher and Poller processes

  • Why: Decouples job scheduling from execution; allows independent scaling and priority handling
  • Consequence: Adds inter-process communication overhead; more processes to monitor and restart

• Concurrency controls via blocked_execution state

  • Why: Transparent to job code; enforced at queue level without job awareness
  • Consequence: Blocked jobs consume database rows; release evaluation requires periodic dispatcher checks

• Real-time job execution (polling-based, not event-driven)
• Distributed consensus or clustering (single database assumed)
• Encrypted job arguments at rest (relies on database-level encryption if needed)

1. Database schema: Solid Queue requires db/queue_schema.rb separate from main app schema—migrations don't auto-run on rails db:migrate without configuration. 2) FOR UPDATE SKIP LOCKED not universal: SQLite/older MySQL versions lack this, falling back to blocking locks—check DB support before deploying. 3) Process cleanup: Processes must be explicitly pruned or stale entries accumulate; see app/models/solid_queue/process/prunable.rb and configure prune intervals. 4) Queue naming: Queue order in config/queue.yml determines priority; typos silently create new queues. 5) Recurring task cron format: Uses fugit gem cron parsing—invalid expressions fail silently at schedule time, not validation time. 6) Rails 7.1+ only: Minimum version is explicit; no backport to 7.0.

• FOR UPDATE SKIP LOCKED — Core performance optimization in Solid Queue that avoids lock contention when polling jobs; essential to understand why the gem works well at scale on PostgreSQL/MySQL 8.0+
• Row-level locking and database transactions — Solid Queue replaces message broker locks with database row locks; understanding transaction isolation is critical for diagnosing concurrency issues
• State machines (job lifecycle) — Executions flow through scheduled → ready → claimed → completed/failed states; this state machine is the core of job processing logic you'll debug
• Semaphore (concurrency control) — Solid Queue implements semaphores in the database to limit concurrent job execution; needed for real-world constraints like 'max 3 concurrent payment jobs'
• Cron expression parsing (fugit gem) — Recurring tasks use cron syntax; understanding fugit's parsing is needed to define recurring job schedules correctly
• Active Job serialization and deserialization — Job payloads are stored as JSON in the database and deserialized at execution time; Solid Queue relies entirely on Active Job's serialization, so understanding GlobalID and custom serializers is essential
• Polling vs. push-based event delivery — Solid Queue polls the database for ready jobs rather than using message brokers; this trade-off affects latency, scalability, and database load profiles

• resque/resque — Classic Redis-backed Rails job queue; Solid Queue is the database-native alternative solving the same problem without Redis dependency
• mperham/sidekiq — Modern Redis-based job processor with rich features; Solid Queue replicates key features (retries, concurrency, recurring jobs) using SQL instead
• delayed/delayed_job — Early database-backed Rails job queue; Solid Queue is the modern, performant successor using FOR UPDATE SKIP LOCKED and optimized polling
• rails/rails — Parent framework; Solid Queue is an official Active Job backend starting in Rails 8, depends on Active Job's serialization and error handling
• rails/solid_cache — Sibling Rails gem providing database-backed caching; shares philosophy of SQL-native backing with Solid Queue

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for SolidQueue::Job concurrency control features

The repo has app/models/solid_queue/job/concurrency_controls.rb and lib/active_job/concurrency_controls.rb which implement concurrency limiting, but there's no visible test/ directory in the file structure. New contributors could add unit and integration tests specifically for concurrency control edge cases (e.g., multiple jobs hitting the same concurrency key, semaphore exhaustion, key expiration). This is critical since concurrency controls are a core differentiator mentioned in the README.

• [ ] Create test/models/solid_queue/job/concurrency_controls_test.rb with tests for semaphore creation and acquisition
• [ ] Add integration tests in test/integration/ for concurrent job execution with concurrency limits
• [ ] Test edge cases: concurrent semaphore acquisition, timeout behavior, key cleanup after job completion
• [ ] Reference app/models/solid_queue/semaphore.rb to understand the underlying persistence model

Add test coverage and documentation for recurring job pause/resume functionality

The repo has app/models/solid_queue/pause.rb and app/models/solid_queue/recurring_task.rb but no visible tests for pausing recurring jobs. The README mentions 'pausing queues' but doesn't explain the pause mechanism for recurring tasks. A contributor could add tests for pause state transitions and documentation showing how to pause/resume recurring jobs in the README or a new guide.

• [ ] Create test/models/solid_queue/pause_test.rb testing pause/resume state transitions
• [ ] Add integration tests verifying that paused recurring tasks don't create new executions
• [ ] Add a 'Pause & Resume' section to README.md with code examples for pausing queues and recurring tasks
• [ ] Test cleanup: verify pause records are properly managed when recurring tasks are deleted

Improve GitHub Actions CI to include appraisal matrix testing and SQLite/MySQL/PostgreSQL database variants

The .github/workflows/main.yml exists but the Appraisals file indicates the project supports Rails 7.1, 7.2, 8.0, 8.1, and main branch. The CI likely doesn't test all Rails versions across all supported databases. Since Solid Queue is database-agnostic (README mentions MySQL, PostgreSQL, SQLite), the CI should verify compatibility across all three. This ensures contributions don't inadvertently break database-specific behavior.

• [ ] Review .github/workflows/main.yml to identify missing Rails version matrix from Appraisals file
• [ ] Expand CI to run tests with BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile, rails_7_2.gemfile, rails_8_0.gemfile, rails_8_1.gemfile, and rails_main.gemfile
• [ ] Add database service containers (MySQL, PostgreSQL) to CI and run full test suite against each database variant
• [ ] Update CI to verify the install generator (lib/generators/solid_queue/install/install_generator.rb) works correctly in matrix

• Add comprehensive test coverage for app/models/solid_queue/queue_selector.rb—currently no dedicated test file visible; this module deserves unit tests covering edge cases like empty queue lists and priority ordering.
• Document the concurrency control workflow with a diagram in README.md or a new CONCURRENCY_CONTROLS.md guide—explain how Semaphore.acquire/release flows work and when to use concurrency_control_key in job definitions.
• Add integration tests for app/models/solid_queue/process/prunable.rb—test that stale processes are correctly identified and cleaned up; ensure pruning doesn't break active process heartbeats.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.