Reference

# Configuration reference

Every Pgbus.configure option, grouped by concern.

## Reading this page

Set any of these in a `Pgbus.configure` block. Durations accept an integer number of seconds or an `ActiveSupport::Duration`. Every option has a default, so you only set what you need. For the knobs most apps touch first, start with [Configuration](https://pgbus.zoolutions.llc/docs/configuration).

## Connection

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `database_url` | String, nil | `nil` | PostgreSQL URL (auto-detected in Rails). |
| `connection_params` | Hash, nil | `nil` | Extra connection parameters merged into the pool. |
| `pool_size` | Integer, nil | `nil (auto)` | Connection pool size; auto-tuned from thread counts when nil. |
| `pool_timeout` | Numeric | `5` | Seconds to wait for a pooled connection. |
| `connects_to` | Hash, nil | `nil` | Rails multi-database config for a dedicated pgbus database. |
| `require_primary` | Boolean | `false` | Reject a job connection that lands on a read-only replica (pg_is_in_recovery) at boot — pooler safety against a read/write splitter routing pgmq reads to a standby. |
| `connection_guc_mode` | Symbol | `:options` | How database.yml GUCs (variables:) reach pgmq connections — :options (libpq startup param) or :session (post-connect SET, for a transaction-mode PgBouncer that rejects the options param). |

## Queues

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `queue_prefix` | String | `"pgbus"` | Prefix for every PGMQ queue name. |
| `default_queue` | String | `"default"` | Queue for jobs without an explicit queue. |
| `priority_levels` | Integer, nil | `nil` | Number of priority sub-queues (2–10); nil disables. |
| `default_priority` | Integer | `1` | Priority for jobs without an explicit one. |
| `group_mode` | Symbol, nil | `nil` | Grouped-read ordering mode for a queue. Experimental — exempt from the 1.0 stability promise. |

## Workers

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `workers` | String / Array | `default: 5` | Worker capsule definitions (string DSL or array). |
| `event_consumers` | String / Array, nil | `nil` | Event-consumer process definitions. |
| `roles` | Array, nil | `nil (all)` | Supervisor role filter — usually set via CLI flags. |
| `execution_mode` | Symbol | `:threads` | Global execution mode (:threads or :async). |
| `polling_interval` | Numeric | `0.1` | Seconds between polls (LISTEN/NOTIFY is primary). |
| `prefetch_limit` | Integer, nil | `nil` | Max in-flight messages per worker. |
| `visibility_timeout` | Duration | `30` | How long a read message stays invisible before retry. |

## Worker recycling

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `max_jobs_per_worker` | Integer, nil | `nil` | Recycle a worker after N jobs. |
| `max_memory_mb` | Integer, nil | `nil` | Recycle a worker above N MB RSS. |
| `max_worker_lifetime` | Duration, nil | `nil` | Recycle a worker after N seconds. |

## Retries & reliability

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `max_retries` | Integer | `5` | Failed reads before routing to the dead-letter queue. |
| `retry_backoff` | Numeric | `5` | Base delay (seconds) for exponential retry backoff. |
| `retry_backoff_max` | Numeric | `300` | Cap on the retry delay. |
| `retry_backoff_jitter` | Float | `0.15` | Jitter factor (0–1) added to retry delays. |
| `circuit_breaker_enabled` | Boolean | `true` | Auto-pause a queue after consecutive failures. |
| `listen_notify` | Boolean | `true` | Use PGMQ LISTEN/NOTIFY for instant wake-up. |
| `zombie_detection` | Boolean | `true` | Detect and reclaim work from crashed workers. |

## Dispatcher & maintenance

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `dispatch_interval` | Numeric | `1.0` | Seconds between dispatcher maintenance ticks. |
| `archive_retention` | Duration, nil | `7.days` | How long to keep archived messages; nil disables cleanup. |
| `idempotency_ttl` | Duration, nil | `7.days` | How long processed-event records are kept for dedup. |

## Outbox

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `outbox_enabled` | Boolean | `false` | Enable the transactional outbox poller. |
| `outbox_poll_interval` | Numeric | `1.0` | Seconds between outbox poll cycles. |
| `outbox_batch_size` | Integer | `100` | Max entries claimed per outbox cycle. |
| `outbox_retention` | Duration, nil | `1.day` | How long to keep published outbox entries. |

## Recurring tasks

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `recurring_tasks` | Hash, nil | `nil` | Recurring task definitions as a hash. |
| `recurring_tasks_files` | Array, nil | `nil` | Paths to recurring.yml files. Replaces the deprecated singular recurring_tasks_file. |
| `recurring_schedule_interval` | Numeric | `1.0` | Seconds between scheduler ticks. |
| `recurring_execution_retention` | Duration, nil | `7.days` | How long to keep recurring execution history. |
| `recurring_enabled` | Boolean | `true` | Run the recurring scheduler (set false to disable it entirely). Replaces the deprecated skip_recurring. |

## Job stats

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `stats_enabled` | Boolean | `true` | Record job execution stats for insights. |
| `stats_retention` | Duration, nil | `30.days` | How long to keep job stats. |
| `stats_flush_size` | Integer | `100` | Buffered stats per worker before a bulk insert. |
| `stats_flush_interval` | Numeric | `5` | Seconds between periodic stat flushes. |

## Dashboard

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `web_auth` | Callable, nil | `nil` | Lambda authorizing dashboard access. |
| `base_controller_class` | String | `"::ActionController::Base"` | Base class for dashboard controllers. |
| `return_to_app_url` | String, nil | `nil` | URL for the "back to app" button. |
| `web_refresh_interval` | Integer | `5000` | Dashboard auto-refresh interval (ms). |
| `web_live_updates` | Boolean | `true` | Enable Turbo Frames auto-refresh. |
| `web_per_page` | Integer | `25` | Dashboard pagination size. |
| `web_filter_sensitive` | Boolean | `true` | Redact sensitive values in dashboard payload views. Replaces the deprecated dashboard_filter_sensitive. |
| `web_filter_parameters` | Array, nil | `nil (auto)` | Parameter-name patterns to redact; nil auto-detects from Rails. Replaces the deprecated dashboard_filter_parameters. |
| `metrics_enabled` | Boolean | `true` | Expose Prometheus gauges on the dashboard. |

## Metrics & logging

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `metrics_backend` | Symbol, Object, nil | `nil` | Metrics adapter: nil, :prometheus, :statsd, or a Backend. |
| `statsd_host` | String | `"127.0.0.1"` | StatsD UDP host. |
| `statsd_port` | Integer | `8125` | StatsD UDP port. |
| `log_format` | Symbol | `:text` | Log formatter (:text or :json). |
| `error_reporters` | Array | `[]` | Callables invoked on caught exceptions. |
| `appsignal_enabled` | Boolean | `true` | Enable the AppSignal subscriber + probe (when the gem is present). |
| `appsignal_probe_enabled` | Boolean | `true` | Enable the minutely AppSignal gauge probe. |

## Health & liveness

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `health_port` | Integer, nil | `nil` | Port for HTTP liveness/readiness probes; nil disables. |
| `health_bind` | String | `"127.0.0.1"` | Bind address for the health server. |
| `stall_threshold` | Numeric | `300` | Seconds without progress before a worker is stalled. |
| `read_timeout` | Numeric | `30` | Read timeout for worker fetches. |
| `drain_timeout` | Numeric | `30` | Seconds to wait for in-flight jobs to finish during graceful shutdown before abandoning them. |

## Streams (SSE)

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `streams_enabled` | Boolean | `true` | Enable the SSE streams transport. |
| `streams_queue_prefix` | String | `"pgbus_stream"` | Prefix for stream queues. |
| `streams_default_retention` | Numeric | `300` | Default stream retention in seconds. |
| `streams_retention` | Hash | `{}` | Per-stream retention overrides. |
| `streams_heartbeat_interval` | Numeric | `15` | SSE heartbeat interval (seconds). |
| `streams_max_connections` | Integer | `2000` | Max SSE connections per web-server process. |
| `streams_idle_timeout` | Numeric | `3600` | Close idle SSE connections after N seconds. |
| `streams_pool_size` | Integer | `5` | Dedicated DB pool for durable-stream publish + replay, isolated from the job pool so a saturated worker pool can't delay broadcasts. Ignored on the shared-ActiveRecord connection path. |
| `streams_pool_timeout` | Numeric | `5` | Seconds to wait for a connection from the dedicated streams pool. |
| `streams_pool_autoscale` | Boolean | `false` | Self-tuning: a periodic maintenance check (on the streamer's idle LISTEN connection — no extra connection) grows the streams pool into a fair share of live Postgres connection headroom under saturation, shrinks back to streams_pool_size when idle, and emergency-shrinks if the DB runs low on connections. Opt-in; no-op on the shared-ActiveRecord path. |
| `streams_pool_max` | Integer, nil | `nil` | Optional hard ceiling for streams-pool autoscaling. nil lets the dynamic per-process fair share of DB headroom be the effective cap. |
| `streams_path` | String, nil | `nil` | Custom SSE endpoint path (auto-detected from mount). |
| `streams_falcon_streaming_body` | Boolean | `false` | Use Falcon-native streaming body instead of hijack. Experimental — exempt from the 1.0 stability promise. |
| `streams_stats_enabled` | Boolean | `false` | Record stream broadcast/connect/disconnect stats. |
| `streams_test_mode` | Boolean | `false` | Return a stub SSE response (auto-enabled by the test helpers). |
| `streams_presence_patterns` | Array | `[]` | Streams (exact string or Regexp) that get connection-driven presence: auto-join on connect, auto-leave on disconnect, heartbeat touch. Experimental — exempt from the 1.0 stability promise. |
| `streams_presence_member` | Callable, nil | `nil` | Custom `->(context) { { id:, metadata: } }` extractor for connection-driven presence; nil uses the built-in Hash/#id extractor. Experimental — exempt from the 1.0 stability promise. |
| `streams_broadcast_queue` | String, nil | `nil` | Dedicated queue for turbo-rails' async broadcast jobs. nil leaves them on the default queue (a broadcasts_to render+broadcast can wait behind long-running jobs). Set a queue name and back it with a worker capsule to isolate broadcast latency. |

## Validation

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `eager_validation` | Boolean | `true` | Validate configuration eagerly at boot. |
| `allowed_global_id_models` | Array, nil | `nil` | Allowlist of models permitted as GlobalID event arguments. |
| `pgmq_schema_mode` | Symbol | `:auto` | PGMQ schema install mode (:auto, :extension, :embedded). |