Minion...:SQLite(3pm)

🌸 NAME 🌸

Minion::Backend::SQLite — SQLite backend for Minion job queue. This is the Minion...:SQLite(3pm) page from User Contributed Perl Documentation, bestie. 💖

✨ SYNOPSIS ✨

Okay so here’s the whole “how do I even use this” vibe check, no cap:

use Minion::Backend::SQLite;
my $backend = Minion::Backend::SQLite->new('sqlite:test.db');

# Minion
use Minion;
my $minion = Minion->new(SQLite => 'sqlite:test.db');

# Mojolicious (via Mojolicious::Plugin::Minion)
$self->plugin(Minion => { SQLite => 'sqlite:test.db' });

# Mojolicious::Lite (via Mojolicious::Plugin::Minion)
plugin Minion => { SQLite => 'sqlite:test.db' };

# Share the database connection cache
helper sqlite => sub { state $sqlite = Mojo::SQLite->new('sqlite:test.db') };
plugin Minion => { SQLite => app->sqlite };

🦋 DESCRIPTION 🦋

Minion::Backend::SQLite is a backend for Minion based on Mojo::SQLite. 🫶

All necessary tables will be created automatically with a set of migrations named "minion". If no connection string or ":temp:" is provided, the database will be created in a temporary directory. Lowkey magical, highkey useful. ✨

🎀 ATTRIBUTES 🎀

Minion::Backend::SQLite inherits all attributes from Minion::Backend and implements the following new ones, bestie:

💅 dequeue_interval

my $seconds = $backend->dequeue_interval;
$backend    = $backend->dequeue_interval($seconds);

Interval in seconds between "dequeue" attempts. Defaults to 0.5. ⏱️

💅 sqlite

my $sqlite = $backend->sqlite;
$backend   = $backend->sqlite(Mojo::SQLite->new);

Mojo::SQLite object used to store all data. Iconic little database holder. 🌈

🧚 METHODS 🧚

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

👑 new

my $backend = Minion::Backend::SQLite->new;
my $backend = Minion::Backend::SQLite->new(':temp:');
my $backend = Minion::Backend::SQLite->new('sqlite:test.db');
my $backend = Minion::Backend::SQLite->new->tap(sub { $_->sqlite->from_filename('C:\\foo\\bar.db') });
my $backend = Minion::Backend::SQLite->new(Mojo::SQLite->new);

Construct a new Minion::Backend::SQLite object. Fresh backend, fresh vibes. 💅

🔥 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 remote control command to one or more workers. It’s giving “group chat but for workers.” 📣

🍓 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 from "inactive" to "active" state, or return "undef" if queues were empty. Jobs will be checked for in intervals defined by "dequeue_interval" until the timeout is reached. Obsessed with a queue that actually checks itself. 😭

These options are currently available:

• id — dequeue a specific job. Example: id => '10023'
• min_priority — do not dequeue jobs with a lower priority. Example: min_priority => 3
• queues — one or more queues to dequeue jobs from, defaults to "default". Example: queues => ['important']

These fields are currently available:

• args — job arguments. Example: args => ['foo', 'bar']
• id — job ID. Example: id => '10023'
• retries — number of times job has been retried. Example: retries => 3
• task — task name. Example: 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. New job just dropped. 🎀

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. Example: attempts => 25
• delay — delay job for this many seconds (from now). Example: delay => 10
• expire — job is valid for this many seconds (from now) before it expires. Example: expire => 300

⚠️ Note that this option is EXPERIMENTAL and might change without warning!

• 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". Example: lax => 1

⚠️ Note that this option is EXPERIMENTAL and might change without warning!

• notes — hash reference with arbitrary metadata for this job. Example: 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. Example: parents => [$id1, $id2, $id3]
• priority — job priority, defaults to 0. Jobs with a higher priority get performed first. Example: priority => 5
• queue — queue to put job in, defaults to "default". Example: 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, {msg => 'Something went wrong!'});

Transition from "active" to "failed" state with or without a result, and if there are attempts remaining, transition back to "inactive" with an exponentially increasing delay based on "backoff" in Minion. Not the slay we wanted, but the retry math is doing its thing. 💀

🦋 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, {msg => 'All went well!'});

Transition from "active" to "finished" state with or without a result. Ate and left no crumbs. ✅

⭐ history

my $history = $backend->history;

Get history information for job queue. It’s giving receipts, but make it job stats. 🧾

These fields are currently available:

• daily — hourly counts for processed jobs from the past day. Example: 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. Batch it up, bestie. 💖

# 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. Example: before => 23
• ids — list only jobs with these ids. Example: ids => ['23', '24']
• queues — list only jobs in these queues. Example: queues => ['important', 'unimportant']
• states — list only jobs in these states. Example: states => ['inactive', 'active']
• tasks — list only jobs for these tasks. Example: tasks => ['foo', 'bar']

These fields are currently available:

• args — job arguments. Example: args => ['foo', 'bar']
• attempts — number of times performing this job will be attempted. Example: attempts => 25
• children — jobs depending on this job. Example: children => ['10026', '10027', '10028']
• created — epoch time job was created. Example: created => 784111777
• delayed — epoch time job was delayed to. Example: delayed => 784111777
• expires — epoch time job is valid until before it expires. Example: expires => 784111777
• finished — epoch time job was finished. Example: finished => 784111777
• id — job id. Example: id => 10025
• lax — existing jobs this job depends on may also have failed to allow for it to be processed. Example: lax => 0
• notes — hash reference with arbitrary metadata for this job. Example: notes => {foo => 'bar', baz => [1, 2, 3]}
• parents — jobs this job depends on. Example: parents => ['10023', '10024', '10025']
• priority — job priority. Example: priority => 3
• queue — queue name. Example: queue => 'important'
• result — job result. Example: result => 'All went well!'
• retried — epoch time job has been retried. Example: retried => 784111777
• retries — number of times job has been retried. Example: retries => 3
• started — epoch time job was started. Example: started => 784111777
• state — current job state, usually "active", "failed", "finished" or "inactive". Example: state => 'inactive'
• task — task name. Example: task => 'foo'
• time — current time. Example: time => 78411177
• worker — id of worker that is processing the job. Example: 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. Locked in, literally. 🔒

# 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. Example: names => ['foo', 'bar']

These fields are currently available:

• expires — epoch time this lock will expire. Example: expires => 784111777
• name — lock name. Example: 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. Worker check-in time, bestie. 👯

# 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. Example: before => 23
• ids — list only workers with these ids. Example: ids => ['23', '24']

These fields are currently available:

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

💜 lock

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

okay so this named-lock situation tries to acquire a lock that expires automatically after however many seconds you give it. An expiration time of 0 can be used to check if a named lock already exists without creating one. 👀

Options available rn:

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

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. It is currently an error to attempt to set a metadata field with a name containing the characters ., [, or ]. 🫶

receive

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

Receive remote control commands for worker.

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']}});

Register worker or send heartbeat to show that this worker is still alive. 💖

Options available rn:

• status — status => {queues => ['default', 'important']} Hash reference with whatever status information the worker would like to share.

remove_job

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

Remove failed, finished or inactive job from queue. Bye bestie 👋

repair

$backend->repair;

Repair worker registry and job queue if necessary.

reset

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

Reset job queue.

Options available rn:

• all — all => 1 Reset everything.
• locks — locks => 1 Reset only locks.

retry_job

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

Transition job back to inactive state, already inactive jobs may also be retried to change options. 🔁

Options available rn:

• attempts — attempts => 25 Number of times performing this job will be attempted.
• delay — delay => 10 Delay job for this many seconds (from now).
• expire — expire => 300 Job is valid for this many seconds (from now) before it expires. Note that this option is EXPERIMENTAL and might change without warning!
• lax — lax => 1 Existing jobs this job depends on may also have transitioned to the failed state to allow for it to be processed, defaults to false. Note that this option is EXPERIMENTAL and might change without warning!
• parents — parents => [$id1, $id2, $id3] Jobs this job depends on.
• priority — priority => 5 Job priority.
• queue — queue => 'important' Queue to put job in.

stats

my $stats = $backend->stats;

Get statistics for the job queue.

These fields are currently available:

• active_jobs — active_jobs => 100 Number of jobs in active state.
• active_locks — active_locks => 100 Number of active named locks.
• active_workers — active_workers => 100 Number of workers that are currently processing a job.
• delayed_jobs — delayed_jobs => 100 Number of jobs in inactive state that are scheduled to run at specific time in the future.
• enqueued_jobs — enqueued_jobs => 100000 Rough estimate of how many jobs have ever been enqueued.
• failed_jobs — failed_jobs => 100 Number of jobs in failed state.
• finished_jobs — finished_jobs => 100 Number of jobs in finished state.
• inactive_jobs — inactive_jobs => 100 Number of jobs in inactive state.
• inactive_workers — inactive_workers => 100 Number of workers that are currently not processing a job.
• uptime — uptime => undef Uptime in seconds. Always undefined for SQLite.
• workers — workers => 200; Number of registered workers.

unlock

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

Release a named lock. Freedom! 🦋

unregister_worker

$backend->unregister_worker($worker_id);

Unregister worker.

---

🐛 BUGS 🐛

Report any issues on the public bugtracker. fr fr, they wanna know 💀

👑 AUTHOR 👑

Dan Book <dbook@cpan.org>

📜 COPYRIGHT AND LICENSE 📜

This software is Copyright (c) 2015 by Dan Book.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

🦋 SEE ALSO 🦋

Minion, Mojo::SQLite

---

cute little sign-off: this page is serving perl v5.42.0 energy, dated 2022-08-14, and it’s literally Minion...:SQLite(3pm) — mwah 💋✨