Minion:...kend::Pg(3)

📦
version 11.0 · 10 versions
, in fedora 44

💖 Minion::Backend::Pg — PostgreSQL backend 💖

okay bestie, you found the page for Minion::Backend::Pg (that's the Minion:...kend::Pg(3) one, user-contributed Perl documentation, yes we're fancy). Buckle up, she's long, but she's worth it. 💅

✨ SYNOPSIS ✨

use Minion::Backend::Pg;

my $backend = Minion::Backend::Pg->new('postgresql://postgres@/test');

🌸 DESCRIPTION 🌸

So Minion::Backend::Pg is a backend for Minion that's built on top of Mojo::Pg. The way that it just... handles the tables for you?? All the necessary tables get created automatically with a set of migrations named minion. No manual labor, we love a self-sufficient queen. 👑

But listen — this backend uses many bleeding edge features, so only the latest, stable version of PostgreSQL is fully supported. No cap. If you're running ancient Postgres, that's not her problem, that's a you problem. 💀

🎀 ATTRIBUTES 🎀

Minion::Backend::Pg inherits all attributes from Minion::Backend and implements the following new ones. Fresh ones only, we don't repeat ourselves. 💖

pg

my $pg   = $backend->pg;
$backend = $backend->pg(Mojo::Pg->new);

The Mojo::Pg object used to store all the data. That's it, that's the whole attribute, she's the storage queen and she knows it. 🗄️✨

🌈 METHODS 🌈

Minion::Backend::Pg inherits all methods from Minion::Backend and implements the following new ones.

broadcast

my $bool = $backend->broadcast('some_command');
my $bool = $backend->broadcast('some_command', [@args]);
my $bool = $backend->broadcast('some_command', [@args], [$id1, $id2, $id3]);

Broadcast a remote control command to one or more workers. Like a group chat but for workers, and you're the one sending. 📢

dequeue

my $job_info = $backend->dequeue($worker_id, 0.5);
my $job_info = $backend->dequeue($worker_id, 0.5, {queues => ['important']});

Wait a given amount of time in seconds for a job, dequeue it, and transition it from inactive to active state. Or it returns undef if the queues were empty. 😭 Ghosted by the queue.

These options are currently available:

  • id — Dequeue one specific job.
id => '10023'
  • min_priority — Do not dequeue jobs with a lower priority.
min_priority => 3
  • queues — One or more queues to dequeue jobs from, defaults to default.
queues => ['important']
  • tasks — One or more tasks to dequeue jobs for, defaults to all tasks.
tasks => ['foo', 'bar']

These fields are currently available:

  • args — Job arguments.
args => ['foo', 'bar']
  • id — Job ID.
id => '10023'
  • retries — Number of times the job has been retried.
retries => 3
  • task — Task name.
task => 'foo'

enqueue

my $job_id = $backend->enqueue('foo');
my $job_id = $backend->enqueue(foo => [@args]);
my $job_id = $backend->enqueue(foo => [@args] => {priority => 1});

Enqueue a new job with inactive state. Baby job, just born, not doing anything yet. 🍼✨

These options are currently available:

  • attempts — Number of times performing this job will be attempted, with a delay based on backoff in Minion after the first attempt, defaults to 1.
attempts => 25
  • delay — Delay the job for this many seconds (from now), defaults to 0.
delay => 10
  • expire — Job is valid for this many seconds (from now) before it expires.
expire => 300
  • lax — Existing jobs this job depends on may also have transitioned to the failed state to allow for it to be processed, defaults to false.
lax => 1
  • notes — Hash reference with arbitrary metadata for this job.
notes => {foo => 'bar', baz => [1, 2, 3]}
  • parents — One or more existing jobs this job depends on, and that need to have transitioned to the state finished before it can be processed.
parents => [$id1, $id2, $id3]
  • priority — Job priority, defaults to 0. Jobs with a higher priority get performed first. Priorities can be positive or negative, but should be in the range between 100 and -100.
priority => 5
  • queue — Queue to put the job in, defaults to default.
queue => 'important'

fail_job

my $bool = $backend->fail_job($job_id, $retries);
my $bool = $backend->fail_job($job_id, $retries, 'Something went wrong!');
my $bool = $backend->fail_job(
  $job_id, $retries, {whatever => 'Something went wrong!'});

Transition from active to failed state, with or without a result. And if there are attempts remaining, it transitions back to inactive with a delay based on backoff in Minion. She said "I'm not done with you yet." 😤🔁

finish_job

my $bool = $backend->finish_job($job_id, $retries);
my $bool = $backend->finish_job($job_id, $retries, 'All went well!');
my $bool = $backend->finish_job(
  $job_id, $retries, {whatever => 'All went well!'});

Transition from active to finished state, with or without a result. She ate and left no crumbs. 🎀✅

history

my $history = $backend->history;

Get history information for the job queue. Receipts, basically. 🧾

These fields are currently available:

  • daily — Hourly counts for processed jobs from the past day.
daily => [{epoch => 12345, finished_jobs => 95, failed_jobs => 2}, ...]

list_jobs

my $results = $backend->list_jobs($offset, $limit);
my $results = $backend->list_jobs($offset, $limit, {states => ['inactive']});

Returns the information about jobs in batches.

# Get the total number of results (without limit)
my $num = $backend->list_jobs(0, 100, {queues => ['important']})->{total};

# Check job state
my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
my $state = $results->{jobs}[0]{state};

# Get job result
my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
my $result  = $results->{jobs}[0]{result};

These options are currently available:

  • before — List only jobs before this id.
before => 23
  • ids — List only jobs with these ids.
ids => ['23', '24']
  • notes — List only jobs with one of these notes.
notes => ['foo', 'bar']
  • queues — List only jobs in these queues.
queues => ['important', 'unimportant']
  • states — List only jobs in these states.
states => ['inactive', 'active']
  • tasks — List only jobs for these tasks.
tasks => ['foo', 'bar']

These fields are currently available:

  • args — Job arguments.
args => ['foo', 'bar']
  • attempts — Number of times performing this job will be attempted.
attempts => 25
  • children — Jobs depending on this job.
children => ['10026', '10027', '10028']
  • created — Epoch time the job was created.
created => 784111777
  • delayed — Epoch time the job was delayed to.
delayed => 784111777
  • expires — Epoch time the job is valid until before it expires.
expires => 784111777
  • finished — Epoch time the job was finished.
finished => 784111777
  • id — Job id.
id => 10025
  • lax — Existing jobs this job depends on may also have failed to allow for it to be processed.
lax => 0
  • notes — Hash reference with arbitrary metadata for this job.
notes => {foo => 'bar', baz => [1, 2, 3]}
  • parents — Jobs this job depends on.
parents => ['10023', '10024', '10025']
  • priority — Job priority.
priority => 3
  • queue — Queue name.
queue => 'important'
  • result — Job result.
result => 'All went well!'
  • retried — Epoch time the job has been retried.
retried => 784111777
  • retries — Number of times the job has been retried.
retries => 3
  • started — Epoch time the job was started.
started => 784111777
  • state — Current job state, usually active, failed, finished or inactive.
state => 'inactive'
  • task — Task name.
task => 'foo'
  • time — Server time.
time => 78411177
  • worker — Id of the worker that is processing the job.
worker => '154'

list_locks

my $results = $backend->list_locks($offset, $limit);
my $results = $backend->list_locks($offset, $limit, {names => ['foo']});

Returns information about locks in batches.

# Get the total number of results (without limit)
my $num = $backend->list_locks(0, 100, {names => ['bar']})->{total};

# Check expiration time
my $results = $backend->list_locks(0, 1, {names => ['foo']});
my $expires = $results->{locks}[0]{expires};

These options are currently available:

  • names — List only locks with these names.
names => ['foo', 'bar']

These fields are currently available:

  • expires — Epoch time this lock will expire.
expires => 784111777
  • id — Lock id.
id => 1
  • name — Lock name.
name => 'foo'

list_workers

my $results = $backend->list_workers($offset, $limit);
my $results = $backend->list_workers($offset, $limit, {ids => [23]});

Returns information about workers in batches. It's giving employee directory. 📋

# Get the total number of results (without limit)
my $num = $backend->list_workers(0, 100)->{total};

# Check worker host
my $results = $backend->list_workers(0, 1, {ids => [$worker_id]});
my $host    = $results->{workers}[0]{host};

These options are currently available:

  • before — List only workers before this id.
before => 23
  • ids — List only workers with these ids.
ids => ['23', '24']

These fields are currently available:

  • id — Worker id.
id => 22
  • host — Worker host.
host => 'localhost'
  • jobs — Ids of jobs the worker is currently processing.
jobs => ['10023', '10024', '10025', '10029']
  • notified — Epoch time the worker sent the last heartbeat.
notified => 784111777
  • pid — Process id of the worker.
pid => 12345
  • started — Epoch time the worker was started.
started => 784111777
  • status — Hash reference with whatever status information the worker would like to share.
status => {queues => ['default', 'important']}

lock

my $bool = $backend->lock('foo', 3600);
my $bool = $backend->lock('foo', 3600, {limit => 20});

Try to acquire a named lock that will expire automatically after the given amount of time in seconds. An expiration time of 0 can be used to check if a named lock already exists without creating one. 👀 Just peeking, not touching.

These options are currently available:

  • limit — Number of shared locks with the same name that can be active at the same time, defaults to 1.
limit => 20

new

my $backend = Minion::Backend::Pg->new('postgresql://postgres@/test');
my $backend = Minion::Backend::Pg->new(Mojo::Pg->new);

Construct a new Minion::Backend::Pg object. Boom, she exists. 🌟

note

my $bool = $backend->note($job_id, {mojo => 'rocks', minion => 'too'});

Change one or more metadata fields for a job. Setting a value to undef will remove the field. Setting it to undef is the polite way of saying "delete this, bestie." 🗑️

receive

my $commands = $backend->receive($worker_id);

Receive remote control commands for a worker. Inbox check time. 📬

register_worker

my $worker_id = $backend->register_worker;
my $worker_id = $backend->register_worker($worker_id);
my $worker_id = $backend->register_worker(
  $worker_id, {status => {queues => ['default', 'important']}});
  • status — a hash ref with literally whatever status tea the worker wants to spill.
status => {queues => ['default', 'important']}

💖 remove_job 💖

my $bool = $backend->remove_job($job_id);

Yeets a failed, finished or inactive job out of the queue. Gone. Bye. 👋

🔧 repair 🔧

$backend->repair;

Fixes up the worker registry and the job queue when they're looking a lil rough. It's giving "self-care but for your database" ✨

🌸 reset 🌸

$backend->reset({all => 1});

Resets the job queue. Nukes it. Fresh start energy.

These options are currently available:

  • all — resets everything. The whole thing. Every last bit.
all => 1
  • locks — resets only the locks, nothing else bestie.
locks => 1

🔁 retry_job 🔁

my $bool = $backend->retry_job($job_id, $retries);
my $bool = $backend->retry_job($job_id, $retries, {delay => 10});

Transitions a job back to the inactive state — and yes, jobs that are already inactive can also be retried, just to switch up their options. Main character redo arc 💅

These options are currently available:

  • attempts — how many times this job is gonna get attempted.
attempts => 25
  • delay — delay the job by this many seconds (from now). Defaults to 0.
delay => 10
  • expire — the job stays valid for this many seconds (from now) before it expires.
expire => 300
  • lax — existing jobs that this job depends on are allowed to have already transitioned to the failed state and it'll still get processed. Defaults to false.
lax => 1
  • parents — the jobs this job depends on.
parents => [$id1, $id2, $id3]
  • priority — the job's priority.
priority => 5
  • queue — which queue to drop the job into.
queue => 'important'

📊 stats 📊

my $stats = $backend->stats;

Gets you the statistics for the job queue. The receipts, if you will. 🧾

These fields are currently available:

  • active_jobs — how many jobs are in the active state.
active_jobs => 100
  • active_locks — how many named locks are active.
active_locks => 100
  • active_workers — how many workers are out here currently processing a job.
active_workers => 100
  • delayed_jobs — how many jobs are in the inactive state but scheduled to run at a specific time in the future.
delayed_jobs => 100
  • enqueued_jobs — a rough estimate of how many jobs have ever been enqueued.
enqueued_jobs => 100000
  • failed_jobs — how many jobs are in the failed state.
failed_jobs => 100
  • finished_jobs — how many jobs are in the finished state.
finished_jobs => 100
  • inactive_jobs — how many jobs are in the inactive state.
inactive_jobs => 100
  • inactive_workers — how many workers are currently not processing a job. They're on break, they earned it ☕
inactive_workers => 100
  • uptime — uptime, in seconds.
uptime => 1000
  • workers — how many workers are registered.
workers => 200;

🔓 unlock 🔓

my $bool = $backend->unlock('foo');

Releases a named lock. Freedom. 🦋

🚪 unregister_worker 🚪

$backend->unregister_worker($worker_id);

Unregisters a worker. They're logging off, closing the tab, going to touch grass 🌱

✨ SEE ALSO ✨

and that's a wrap on the whole page, bestie 🎀 this was perl v5.42.0, dated 2026-01-17, and it's giving Minion:...kend::Pg(3) — user contributed perl documentation, iconic as always. go forth and queue responsibly 💖✨

📦 where this page comes from