Database Setup

August 20, 2026 ยท View on GitHub

PgQueuer requires initial setup in your PostgreSQL database: tables, triggers, and functions for job queuing and processing.

Table structure

PgQueuer uses four primary tables:

  • pgqueuer: the active job queue
  • pgqueuer_log: job execution history and audit trail
  • pgqueuer_statistics: aggregated statistics
  • pgqueuer_schedules: recurring schedule definitions

Installation

Install PgQueuer schema via the CLI. Make sure your PostgreSQL environment variables (PGHOST, PGUSER, PGPASSWORD, PGDATABASE) are set, or pass --pg-dsn / set PGDSN with a full connection string:

pgq install

To see what SQL will be executed without applying it, use the offline pgq sql group. It never connects to a database, so you can pipe the script to psql or hand it to your migration tool (Flyway, sqitch, Alembic) or a DBA with restricted permissions (see Database Permissions):

pgq sql install
pgq sql install | psql -v ON_ERROR_STOP=1
pgq sql upgrade > migrations/V2__pgqueuer_upgrade.sql

Uninstallation

pgq uninstall

Upgrades

Apply schema migrations after upgrading PgQueuer:

pgq upgrade

Verification

Check that all required objects exist:

pgq verify --expect present

Check that the schema has been removed:

pgq verify --expect absent

The command exits with code 1 if any mismatches are detected.

Adjusting durability

PgQueuer tables are installed with durable settings by default. You can select a different durability level at install time:

pgq install --durability balanced

Or change the durability of existing tables without data loss:

pgq durability volatile

See CLI Reference for full details on volatile, balanced, and durable modes.

Autovacuum optimization

After installation, tune PostgreSQL autovacuum settings for PgQueuer tables:

pgq autovac

This applies recommended values that reduce bloat on the queue while keeping the log table mostly append-only. Reset to system defaults with:

pgq autovac --rollback