Reference

# Configuration reference

Every global option you can set in a SidekiqUniqueJobs.configure block, grouped by concern.

## The configure block

Set global defaults once, at boot.

Global configuration lives in a `SidekiqUniqueJobs.configure` block — typically in your Sidekiq initializer, alongside the middleware. Every value here is a **default**: a worker's own `sidekiq_options` always wins over the global setting. For the per-worker keys, see [Worker options](https://sidekiq-unique-jobs.zoolutions.llc/docs/worker-options).

```ruby
# config/initializers/sidekiq.rb
SidekiqUniqueJobs.configure do |config|
  config.enabled          = true
  config.lock_ttl         = nil     # locks don't expire on their own
  config.lock_timeout     = 0       # fail fast when a lock is held
  config.lock_prefix      = "uniquejobs"
  config.on_conflict      = nil     # defer to each worker's on_conflict
  config.reaper           = :ruby   # safe orphan cleanup
  config.reaper_count     = 1000
  config.reaper_interval  = 600
  config.digest_algorithm = :legacy
end
```

The tables below list every option, its type, its default, and what it controls. They are generated from the gem's real config struct and drift-tested against it, so a renamed or added option fails the build until this reference is updated.

## Locking

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | Boolean | true | Master switch. Set false to disable uniqueness globally (e.g. in tests). |
| `lock_ttl` | Integer, nil | nil | Default lock expiration in seconds; nil means the lock never expires on its own. |
| `lock_timeout` | Integer | 0 | Default seconds to wait for a contended lock; 0 means don't wait (fail fast). |
| `lock_prefix` | String | "uniquejobs" | Prefix for every Redis lock key. |
| `lock_info` | Boolean | false | Store extra lock metadata (worker, args, timestamp) for debugging. Adds overhead. |
| `on_conflict` | Symbol, Hash, nil | nil | Global default conflict strategy when a worker doesn't set its own; nil defers entirely to per-worker config. |

## Reaper (orphan cleanup)

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `reaper` | Symbol, Boolean | :ruby | Orphan-lock reaper mode: :ruby (default, safe), :lua (faster, briefly blocks Redis), or :none/false to disable. |
| `reaper_count` | Integer | 1000 | Maximum orphaned locks reaped per cycle. Keep low (≤1000) with the :lua reaper. |
| `reaper_interval` | Integer | 600 | Seconds between reaper runs (default 10 minutes). |
| `reaper_timeout` | Integer | 10 | Maximum seconds a single reaper run may take before it stops. |
| `reaper_resurrector_interval` | Integer | 3600 | Seconds between checks that the reaper thread is still alive (default 1 hour). |
| `reaper_resurrector_enabled` | Boolean | false | Restart the reaper thread if it dies. Off by default. |

## Digest & storage

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `digest_algorithm` | Symbol | :legacy | How the uniqueness digest is hashed: :legacy (MD5) or :modern (FIPS-compatible). Changing this changes every digest. |
| `max_history` | Integer | 1000 | Number of changelog history entries retained. |

## Execution & errors

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `locksmith_executor` | Executor, nil | nil | Concurrent-Ruby executor for Locksmith promises; nil lazily builds a bounded default pool (prevents unbounded thread growth). |
| `raise_on_config_error` | Boolean | false | Raise instead of warn when a worker declares an invalid lock configuration. |
| `logger_enabled` | Boolean | true | Enable the gem's internal logging. |
| `debug_lua` | Boolean | false | Log Lua script execution. Slow — for debugging only. |