1Minion::Backend::Pg(3)User Contributed Perl DocumentationMinion::Backend::Pg(3)
2
3
4

NAME

6       Minion::Backend::Pg - PostgreSQL backend
7

SYNOPSIS

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

DESCRIPTION

14       Minion::Backend::Pg is a backend for Minion based on Mojo::Pg. All
15       necessary tables will be created automatically with a set of migrations
16       named "minion". Note that this backend uses many bleeding edge
17       features, so only the latest, stable version of PostgreSQL is fully
18       supported.
19

ATTRIBUTES

21       Minion::Backend::Pg inherits all attributes from Minion::Backend and
22       implements the following new ones.
23
24   pg
25         my $pg   = $backend->pg;
26         $backend = $backend->pg(Mojo::Pg->new);
27
28       Mojo::Pg object used to store all data.
29

METHODS

31       Minion::Backend::Pg inherits all methods from Minion::Backend and
32       implements the following new ones.
33
34   broadcast
35         my $bool = $backend->broadcast('some_command');
36         my $bool = $backend->broadcast('some_command', [@args]);
37         my $bool = $backend->broadcast('some_command', [@args], [$id1, $id2, $id3]);
38
39       Broadcast remote control command to one or more workers.
40
41   dequeue
42         my $job_info = $backend->dequeue($worker_id, 0.5);
43         my $job_info = $backend->dequeue($worker_id, 0.5, {queues => ['important']});
44
45       Wait a given amount of time in seconds for a job, dequeue it and
46       transition from "inactive" to "active" state, or return "undef" if
47       queues were empty.
48
49       These options are currently available:
50
51       id
52           id => '10023'
53
54         Dequeue a specific job.
55
56       min_priority
57           min_priority => 3
58
59         Do not dequeue jobs with a lower priority.
60
61       queues
62           queues => ['important']
63
64         One or more queues to dequeue jobs from, defaults to "default".
65
66       These fields are currently available:
67
68       args
69           args => ['foo', 'bar']
70
71         Job arguments.
72
73       id
74           id => '10023'
75
76         Job ID.
77
78       retries
79           retries => 3
80
81         Number of times job has been retried.
82
83       task
84           task => 'foo'
85
86         Task name.
87
88   enqueue
89         my $job_id = $backend->enqueue('foo');
90         my $job_id = $backend->enqueue(foo => [@args]);
91         my $job_id = $backend->enqueue(foo => [@args] => {priority => 1});
92
93       Enqueue a new job with "inactive" state.
94
95       These options are currently available:
96
97       attempts
98           attempts => 25
99
100         Number of times performing this job will be attempted, with a delay
101         based on "backoff" in Minion after the first attempt, defaults to 1.
102
103       delay
104           delay => 10
105
106         Delay job for this many seconds (from now), defaults to 0.
107
108       expire
109           expire => 300
110
111         Job is valid for this many seconds (from now) before it expires.
112
113       lax
114           lax => 1
115
116         Existing jobs this job depends on may also have transitioned to the
117         "failed" state to allow for it to be processed, defaults to "false".
118         Note that this option is EXPERIMENTAL and might change without
119         warning!
120
121       notes
122           notes => {foo => 'bar', baz => [1, 2, 3]}
123
124         Hash reference with arbitrary metadata for this job.
125
126       parents
127           parents => [$id1, $id2, $id3]
128
129         One or more existing jobs this job depends on, and that need to have
130         transitioned to the state "finished" before it can be processed.
131
132       priority
133           priority => 5
134
135         Job priority, defaults to 0. Jobs with a higher priority get
136         performed first. Priorities can be positive or negative, but should
137         be in the range between 100 and -100.
138
139       queue
140           queue => 'important'
141
142         Queue to put job in, defaults to "default".
143
144   fail_job
145         my $bool = $backend->fail_job($job_id, $retries);
146         my $bool = $backend->fail_job($job_id, $retries, 'Something went wrong!');
147         my $bool = $backend->fail_job(
148           $job_id, $retries, {whatever => 'Something went wrong!'});
149
150       Transition from "active" to "failed" state with or without a result,
151       and if there are attempts remaining, transition back to "inactive" with
152       a delay based on "backoff" in Minion.
153
154   finish_job
155         my $bool = $backend->finish_job($job_id, $retries);
156         my $bool = $backend->finish_job($job_id, $retries, 'All went well!');
157         my $bool = $backend->finish_job(
158           $job_id, $retries, {whatever => 'All went well!'});
159
160       Transition from "active" to "finished" state with or without a result.
161
162   history
163         my $history = $backend->history;
164
165       Get history information for job queue.
166
167       These fields are currently available:
168
169       daily
170           daily => [{epoch => 12345, finished_jobs => 95, failed_jobs => 2}, ...]
171
172         Hourly counts for processed jobs from the past day.
173
174   list_jobs
175         my $results = $backend->list_jobs($offset, $limit);
176         my $results = $backend->list_jobs($offset, $limit, {states => ['inactive']});
177
178       Returns the information about jobs in batches.
179
180         # Get the total number of results (without limit)
181         my $num = $backend->list_jobs(0, 100, {queues => ['important']})->{total};
182
183         # Check job state
184         my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
185         my $state = $results->{jobs}[0]{state};
186
187         # Get job result
188         my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
189         my $result  = $results->{jobs}[0]{result};
190
191       These options are currently available:
192
193       before
194           before => 23
195
196         List only jobs before this id.
197
198       ids
199           ids => ['23', '24']
200
201         List only jobs with these ids.
202
203       notes
204           notes => ['foo', 'bar']
205
206         List only jobs with one of these notes.
207
208       queues
209           queues => ['important', 'unimportant']
210
211         List only jobs in these queues.
212
213       states
214           states => ['inactive', 'active']
215
216         List only jobs in these states.
217
218       tasks
219           tasks => ['foo', 'bar']
220
221         List only jobs for these tasks.
222
223       These fields are currently available:
224
225       args
226           args => ['foo', 'bar']
227
228         Job arguments.
229
230       attempts
231           attempts => 25
232
233         Number of times performing this job will be attempted.
234
235       children
236           children => ['10026', '10027', '10028']
237
238         Jobs depending on this job.
239
240       created
241           created => 784111777
242
243         Epoch time job was created.
244
245       delayed
246           delayed => 784111777
247
248         Epoch time job was delayed to.
249
250       expires
251           expires => 784111777
252
253         Epoch time job is valid until before it expires.
254
255       finished
256           finished => 784111777
257
258         Epoch time job was finished.
259
260       id
261           id => 10025
262
263         Job id.
264
265       lax
266           lax => 0
267
268         Existing jobs this job depends on may also have failed to allow for
269         it to be processed.
270
271       notes
272           notes => {foo => 'bar', baz => [1, 2, 3]}
273
274         Hash reference with arbitrary metadata for this job.
275
276       parents
277           parents => ['10023', '10024', '10025']
278
279         Jobs this job depends on.
280
281       priority
282           priority => 3
283
284         Job priority.
285
286       queue
287           queue => 'important'
288
289         Queue name.
290
291       result
292           result => 'All went well!'
293
294         Job result.
295
296       retried
297           retried => 784111777
298
299         Epoch time job has been retried.
300
301       retries
302           retries => 3
303
304         Number of times job has been retried.
305
306       started
307           started => 784111777
308
309         Epoch time job was started.
310
311       state
312           state => 'inactive'
313
314         Current job state, usually "active", "failed", "finished" or
315         "inactive".
316
317       task
318           task => 'foo'
319
320         Task name.
321
322       time
323           time => 78411177
324
325         Server time.
326
327       worker
328           worker => '154'
329
330         Id of worker that is processing the job.
331
332   list_locks
333         my $results = $backend->list_locks($offset, $limit);
334         my $results = $backend->list_locks($offset, $limit, {names => ['foo']});
335
336       Returns information about locks in batches.
337
338         # Get the total number of results (without limit)
339         my $num = $backend->list_locks(0, 100, {names => ['bar']})->{total};
340
341         # Check expiration time
342         my $results = $backend->list_locks(0, 1, {names => ['foo']});
343         my $expires = $results->{locks}[0]{expires};
344
345       These options are currently available:
346
347       names
348           names => ['foo', 'bar']
349
350         List only locks with these names.
351
352       These fields are currently available:
353
354       expires
355           expires => 784111777
356
357         Epoch time this lock will expire.
358
359       name
360           name => 'foo'
361
362         Lock name.
363
364   list_workers
365         my $results = $backend->list_workers($offset, $limit);
366         my $results = $backend->list_workers($offset, $limit, {ids => [23]});
367
368       Returns information about workers in batches.
369
370         # Get the total number of results (without limit)
371         my $num = $backend->list_workers(0, 100)->{total};
372
373         # Check worker host
374         my $results = $backend->list_workers(0, 1, {ids => [$worker_id]});
375         my $host    = $results->{workers}[0]{host};
376
377       These options are currently available:
378
379       before
380           before => 23
381
382         List only workers before this id.
383
384       ids
385           ids => ['23', '24']
386
387         List only workers with these ids.
388
389       These fields are currently available:
390
391       id
392           id => 22
393
394         Worker id.
395
396       host
397           host => 'localhost'
398
399         Worker host.
400
401       jobs
402           jobs => ['10023', '10024', '10025', '10029']
403
404         Ids of jobs the worker is currently processing.
405
406       notified
407           notified => 784111777
408
409         Epoch time worker sent the last heartbeat.
410
411       pid
412           pid => 12345
413
414         Process id of worker.
415
416       started
417           started => 784111777
418
419         Epoch time worker was started.
420
421       status
422           status => {queues => ['default', 'important']}
423
424         Hash reference with whatever status information the worker would like
425         to share.
426
427   lock
428         my $bool = $backend->lock('foo', 3600);
429         my $bool = $backend->lock('foo', 3600, {limit => 20});
430
431       Try to acquire a named lock that will expire automatically after the
432       given amount of time in seconds. An expiration time of 0 can be used to
433       check if a named lock already exists without creating one.
434
435       These options are currently available:
436
437       limit
438           limit => 20
439
440         Number of shared locks with the same name that can be active at the
441         same time, defaults to 1.
442
443   new
444         my $backend = Minion::Backend::Pg->new('postgresql://postgres@/test');
445         my $backend = Minion::Backend::Pg->new(Mojo::Pg->new);
446
447       Construct a new Minion::Backend::Pg object.
448
449   note
450         my $bool = $backend->note($job_id, {mojo => 'rocks', minion => 'too'});
451
452       Change one or more metadata fields for a job. Setting a value to
453       "undef" will remove the field.
454
455   receive
456         my $commands = $backend->receive($worker_id);
457
458       Receive remote control commands for worker.
459
460   register_worker
461         my $worker_id = $backend->register_worker;
462         my $worker_id = $backend->register_worker($worker_id);
463         my $worker_id = $backend->register_worker(
464           $worker_id, {status => {queues => ['default', 'important']}});
465
466       Register worker or send heartbeat to show that this worker is still
467       alive.
468
469       These options are currently available:
470
471       status
472           status => {queues => ['default', 'important']}
473
474         Hash reference with whatever status information the worker would like
475         to share.
476
477   remove_job
478         my $bool = $backend->remove_job($job_id);
479
480       Remove "failed", "finished" or "inactive" job from queue.
481
482   repair
483         $backend->repair;
484
485       Repair worker registry and job queue if necessary.
486
487   reset
488         $backend->reset({all => 1});
489
490       Reset job queue.
491
492       These options are currently available:
493
494       all
495           all => 1
496
497         Reset everything.
498
499       locks
500           locks => 1
501
502         Reset only locks.
503
504   retry_job
505         my $bool = $backend->retry_job($job_id, $retries);
506         my $bool = $backend->retry_job($job_id, $retries, {delay => 10});
507
508       Transition job back to "inactive" state, already "inactive" jobs may
509       also be retried to change options.
510
511       These options are currently available:
512
513       attempts
514           attempts => 25
515
516         Number of times performing this job will be attempted.
517
518       delay
519           delay => 10
520
521         Delay job for this many seconds (from now), defaults to 0.
522
523       expire
524           expire => 300
525
526         Job is valid for this many seconds (from now) before it expires.
527
528       lax
529           lax => 1
530
531         Existing jobs this job depends on may also have transitioned to the
532         "failed" state to allow for it to be processed, defaults to "false".
533         Note that this option is EXPERIMENTAL and might change without
534         warning!
535
536       parents
537           parents => [$id1, $id2, $id3]
538
539         Jobs this job depends on.
540
541       priority
542           priority => 5
543
544         Job priority.
545
546       queue
547           queue => 'important'
548
549         Queue to put job in.
550
551   stats
552         my $stats = $backend->stats;
553
554       Get statistics for the job queue.
555
556       These fields are currently available:
557
558       active_jobs
559           active_jobs => 100
560
561         Number of jobs in "active" state.
562
563       active_locks
564           active_locks => 100
565
566         Number of active named locks.
567
568       active_workers
569           active_workers => 100
570
571         Number of workers that are currently processing a job.
572
573       delayed_jobs
574           delayed_jobs => 100
575
576         Number of jobs in "inactive" state that are scheduled to run at
577         specific time in the future.
578
579       enqueued_jobs
580           enqueued_jobs => 100000
581
582         Rough estimate of how many jobs have ever been enqueued.
583
584       failed_jobs
585           failed_jobs => 100
586
587         Number of jobs in "failed" state.
588
589       finished_jobs
590           finished_jobs => 100
591
592         Number of jobs in "finished" state.
593
594       inactive_jobs
595           inactive_jobs => 100
596
597         Number of jobs in "inactive" state.
598
599       inactive_workers
600           inactive_workers => 100
601
602         Number of workers that are currently not processing a job.
603
604       uptime
605           uptime => 1000
606
607         Uptime in seconds.
608
609       workers
610           workers => 200;
611
612         Number of registered workers.
613
614   unlock
615         my $bool = $backend->unlock('foo');
616
617       Release a named lock.
618
619   unregister_worker
620         $backend->unregister_worker($worker_id);
621
622       Unregister worker.
623

SEE ALSO

625       Minion, Minion::Guide, <https://minion.pm>, Mojolicious::Guides,
626       <https://mojolicious.org>.
627
628
629
630perl v5.36.0                      2023-01-20            Minion::Backend::Pg(3)
Impressum