Operations

Separate database

Run pgbus in a dedicated database, isolating queue churn from your primary.

Primary or dedicated#

pgbus runs in your primary database by default. For high-volume deployments you can give it a dedicated database — the same pattern SolidQueue uses — so the queue tables' heavy write/vacuum churn doesn't compete with your application's working set.

Point pgbus at the database#

config.connects_to.

config.connects_to follows Rails' multiple-databases API. Leave it nil for the primary; set the writing role for a dedicated database:

config/initializers/pgbus.rb

Pgbus.configure do |c|
  c.connects_to = { database: { writing: :pgbus } }
end

Route migrations to db/pgbus_migrate#

Pass --database=pgbus to any pgbus generator and its migrations go to db/pgbus_migrate/ instead of db/migrate/:

rails generate pgbus:install --database=pgbus
rails generate pgbus:add_recurring --database=pgbus
rails db:migrate:pgbus

The pgbus:update generator detects a separate-database config automatically (from connects_to or by scanning your initializer), so you don't re-specify --database=pgbus on every run.

Wire up database.yml#

Declare the second database with its migrations path so db:migrate:pgbus knows where to look:

config/database.yml

production:
  primary:
    <<: *default
    database: myapp_production
  pgbus:
    <<: *default
    database: myapp_pgbus_production
    migrations_paths: db/pgbus_migrate

Boot-time connections and db:test:purge#

Any code that touches a pgbus model during Rails boot leaves an idle session on the dedicated database for the life of the process. Rails' db:test:purge / db:drop only disconnect the connection they open themselves, so that idle session would block the process's own DROP DATABASE (or kill it via statement_timeout). pgbus guards this automatically: every purge/drop first disconnects pgbus's own connection pools, so db:test:prepare can never wedge on a pgbus session.

For your own boot-time database touches (warm-ups, probes in an initializer), skip them in the rake contexts where a database may not exist yet with Pgbus.database_task?:

config/initializers/pgbus_warmup.rb

Rails.application.config.after_initialize do
  next if Pgbus.database_task? # db:*, assets:* rake tasks

  # ... touch the pgbus database ...
end