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.

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).