Getting started

# Installation

Add the gem, then wire the middleware into your Sidekiq initializer — without it, jobs silently won't be unique.

## Add the gem

Add sidekiq-unique-jobs to your `Gemfile`:

```ruby
gem "sidekiq-unique-jobs", "~> 9.0"
```

Then install it:

```shell
bundle install
```

## Requirements

v9 is a ground-up rewrite that targets modern runtimes. Redis 6.2 is the floor because the lock scripts rely on `LMOVE`.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `Ruby` | runtime | >= 3.2 | Earlier rubies are not supported. |
| `Sidekiq` | gem | >= 8.0 | v9 is Sidekiq 8+ only. |
| `Redis` | server | >= 6.2 | Required for the atomic LMOVE used by the lock scripts. |

## Wire the middleware

The one step that actually turns uniqueness on.

Uniqueness is enforced by two pieces of Sidekiq middleware: a **client** middleware that runs when a job is enqueued, and a **server** middleware that runs when a job executes. Add both in `config/initializers/sidekiq.rb`, and call `SidekiqUniqueJobs::Server.configure` on the server so the reaper and other server-side machinery start up.

```ruby
# config/initializers/sidekiq.rb
Sidekiq.configure_client do |config|
  config.client_middleware do |chain|
    chain.add SidekiqUniqueJobs::Middleware::Client
  end
end

Sidekiq.configure_server do |config|
  config.client_middleware do |chain|
    chain.add SidekiqUniqueJobs::Middleware::Client
  end
  config.server_middleware do |chain|
    chain.add SidekiqUniqueJobs::Middleware::Server
  end
  SidekiqUniqueJobs::Server.configure(config)
end
```

The client middleware is added in **both** blocks on purpose: your web process enqueues jobs, but so do your Sidekiq workers (a job that calls `perform_async` on another job). Registering it on the server as well keeps those enqueues unique too.

> **Warning:** Since v7 the middleware is NOT auto-loaded. If you skip this step, everything installs and boots without error — but no lock is ever taken and your jobs will silently run as duplicates. Adding a `lock:` option to a worker does nothing until the middleware is wired up here.

## Middleware ordering

When you run sidekiq-unique-jobs alongside other middleware gems (apartment-sidekiq, sidekiq-global_id, sidekiq-status, ...), order matters. As a rule of thumb, this gem's middleware should run **last** on both the client and the server chain, so the digest is computed after any other gem has finished rewriting the job payload.

Because `chain.add` appends to the end of the chain, adding these entries after your other middleware is usually enough. If you need to be explicit, Sidekiq's `chain.insert_after` / `chain.insert_before` let you place them precisely.

> **Note:** The README documents the exact ordering for specific gem combinations — start there if uniqueness behaves oddly next to another middleware gem.

## Next steps

The middleware is wired up — now make a job unique. Head to [Quick start](https://sidekiq-unique-jobs.zoolutions.llc/docs/quick-start) to write your first unique worker.