Installing and Setting Up SolidQueue in Rails 8 #

Getting started with SolidQueue is refreshingly simple, especially if you're already familiar with standard Rails workflows.

SolidQueue is built into Rails 8 as a first-party background job processing backend, leveraging Active Job and your existing SQL database. There’s no need to install Redis, no complex configuration files, and no deviation from Rails conventions.

This section walks you through setting up SolidQueue step-by-step, from initializing your project to running your first background job.

We’ll be using PostgreSQL in this example, but SolidQueue works equally well with MySQL and SQLite. All you need is a standard Rails 8 installation and database access. Let’s jump into it.

Step 1: Create a New Rails 8 App (Skip if You're Using an Existing One) #

If you haven’t already created a Rails 8 app, you can do so using:

rails new solid_demo --database=postgresql
cd solid_demo

Make sure your Rails version is 8.0 or higher:

rails -v
#=> Rails 8.x.x

Step 2: Add SolidQueue to Your Gemfile #

SolidQueue is developed by the Rails team but not bundled by default. Add it to your Gemfile:

gem "solid_queue"

Then run:

bundle install

Step 3: Run the SolidQueue Installer #

SolidQueue provides a Rails generator that creates all required database migrations and job models:

bin/rails solid_queue:install

This will generate the necessary migrations and configuration files.

Example output:

create  db/migrate/20250519105000_create_solid_queue_tables.rb

Then migrate your database:

bin/rails db:migrate

This sets up all required tables to store job queues, scheduled jobs, concurrency control metadata, and more.

Step 4: Configure Active Job to Use SolidQueue #

Rails uses Active Job to abstract over various background job libraries. Set SolidQueue as your queue adapter in config/application.rb or your environment file:

#config/application.rb
config.active_job.queue_adapter = :solid_queue

That’s it — now all background jobs in your app will use SolidQueue under the hood.

Step 5: Create Your First Background Job #

When we create a background job in Rails, we define a new class that inherits from ApplicationJob. This base class is a wrapper around Active Job and makes it easy to plug into various job backends — like Sidekiq, Delayed Job, and now, SolidQueue.

You can now generate a job using the standard Rails generator:

bin/rails generate job example

This will create a job file under app/jobs/example_job.rb.

Example content:

class ExampleJob < ApplicationJob
  queue_as :default

  def perform(*args)
    puts "Running background job with args: #{args.inspect}"
  end
end

Explanation:

• queue_as :default tells Rails which queue to use. SolidQueue will pick this up and store the job in the "default" queue in your database.
• perform is the method that gets called when the job runs. You can name your arguments whatever you like, but the method itself must always be called perform.

📌 Note: The method name must be perform. This is what Active Job expects and uses to call your logic later when processing the job.

To actually queue this job for execution, we use Active Job’s API like this::

ExampleJob.perform_later("hello", 123)

This will insert a new row into your database, under the solid_queue_jobs table.

What happens behind the scenes?

• Rails serializes the job details — the job class name, arguments (user.id), queue name, etc.
• SolidQueue stores this data in a special table (usually solid_queue_jobs) as a new row.

If you’re running a worker (which we’ll get into), it will pick up this row and execute WelcomeEmailJob.new.perform(user.id).

You can also run the job immediately with:

WelcomeEmailJob.perform_now(user.id)

This skips the queue and runs the job inline — useful for debugging.

Step 6: Start the Job Processor #

SolidQueue comes with a built-in job runner (also called worker). You can start a job processor (or worker) using:

bin/rails solid_queue:work

This command will continuously poll the database for available jobs and execute them using your application code.

You’ll see log output like:

[SolidQueue] Fetched job ID: 3 from 'default' queue
[SolidQueue] Executing ExampleJob

You can run multiple workers for concurrency:

bin/rails solid_queue:work & bin/rails solid_queue:work

🛠 Note for Development: In development mode, you don’t even need to start a worker separately — SolidQueue runs an inline job processor as part of the rails server. The job processing thread boots automatically when you run bin/rails server, making it seamless to test and debug background jobs without managing extra processes.

Step 7: Optional Features to Explore #

Once the basics are in place, you can explore advanced features like:

• Recurring jobs via solid_queue:recurring_job generator
• Custom queues with job priorities
• Queue pausing/resuming
• Bulk job enqueuing using perform_all_later

For example, to enqueue a recurring job every 15 minutes:

bin/rails generate solid_queue:recurring_job purge_stale_sessions --every="15.minutes"

Debugging and Monitoring #

Since SolidQueue is DB-driven, you can inspect queues and job state directly using SQL:

SELECT * FROM solid_queue_jobs WHERE finished_at IS NULL;

Or write a simple admin dashboard using ActiveRecord models like SolidQueue::Job.

By using the same tools, conventions, and environment as the rest of your Rails application, SolidQueue keeps background job management simple, transparent, and native. No Redis, no external queues — just migrations and models.

You now have a fully-working background job system set up and ready to use in any Rails 8 application.