Installation
Add the gem, install the PGMQ schema, and run the generator.
Requirements#
| Requirement | Version |
|---|---|
Ruby | >= 3.3 |
Rails | >= 7.1 |
PostgreSQL | with PGMQ — extension or embedded SQL |
Add the gem#
Add pgbus to your Gemfile and bundle install:
gem "pgbus"Install the PGMQ schema#
Extension, embedded, or auto.
PGMQ provides the queue tables and functions pgbus builds on. It can be installed as a PostgreSQL extension or as vendored, embedded SQL that needs no extension privileges — useful on managed Postgres where you can't CREATE EXTENSION. The mode is config.pgmq_schema_mode:
| Option | Type | Default | Description |
|---|---|---|---|
:auto | Symbol | :auto | Try the extension, fall back to embedded SQL. The default. |
:extension | Symbol | — | Require the pgmq PostgreSQL extension. |
:embedded | Symbol | — | Use the vendored SQL; no extension needed. |
With the extension route, create it once in your database:
CREATE EXTENSION IF NOT EXISTS pgmq;rake pgbus:pgmq:status (installed vs available) and rake pgbus:pgmq:versions (vendored PGMQ versions). Upgrade the embedded schema with rails generate pgbus:upgrade_pgmq.Run the install generator#
The install generator writes the migrations for pgbus's metadata tables (queue state, processed events, job locks, and so on) and a starter initializer:
rails generate pgbus:install
rails db:migrateChoose the PGMQ schema mode at install time if you don't want the default:
rails generate pgbus:install --pgmq-schema-mode=embeddedrails generate pgbus:update converts a legacy config/pgbus.yml to a Ruby initializer and adds any missing migrations in one pass. See Configuration.A dedicated database#
pgbus can live in your primary database (the default) or in a dedicated one, like SolidQueue. Pass --database=pgbus to route the migrations to db/pgbus_migrate/:
rails generate pgbus:install --database=pgbusSee Separate database for the connects_to config and the database.yml wiring.