Getting started

# Installation

Add the gem, install the PGMQ schema, and run the generator.

## Requirements

| Requirement | Version |
| --- | --- |
| `Ruby` | >= 3.3 |
| `Rails` | >= 7.1 |
| `PostgreSQL` | with [PGMQ](https://github.com/pgmq/pgmq) — extension or embedded SQL |

## Add the gem

Add pgbus to your Gemfile and `bundle install`:

```ruby
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:

```sql
CREATE EXTENSION IF NOT EXISTS pgmq;
```

> **Note:** Two rake tasks report and list versions: `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:

```shell
rails generate pgbus:install
rails db:migrate
```

Choose the PGMQ schema mode at install time if you don't want the default:

```shell
rails generate pgbus:install --pgmq-schema-mode=embedded
```

> **Tip:** Already running an older pgbus? `rails generate pgbus:update` converts a legacy config/pgbus.yml to a Ruby initializer and adds any missing migrations in one pass. See [Configuration](https://pgbus.zoolutions.llc/docs/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/`:

```shell
rails generate pgbus:install --database=pgbus
```

See [Separate database](https://pgbus.zoolutions.llc/docs/separate-database) for the `connects_to` config and the `database.yml` wiring.