Queue::DBI(3pm)

📦

version 2.7.0 · 2 versions

2.7.0 · fedora 43 (latest)
2.7.0 · fedora 44

💖 NAME 💖

okay so bestie, welcome to Queue::DBI — and yeah, this page is from the User Contributed Perl Documentation section (that's what the 3pm in Queue::DBI(3pm) is giving ✨).

It's a queueing module where the whole vibe is safety first, and it uses DBI as the storage system for all your queued data. No cap. 🫶

🌟 VERSION 🌟

Version 2.7.0 💅

✨ SYNOPSIS ✨

This module lets you use a queueing system safely, by preventing backtracking, infinite loops and data loss. Like, it's literally built different. 🦋

The big main character energy of this distribution? An extremely reliable dequeueing mechanism — and you don't even have to use transactions for it. Periodt.

use Queue::DBI;
my $queue = Queue::DBI->new(
        'queue_name'      => $queue_name,
        'database_handle' => $dbh,
        'cleanup_timeout' => 3600,
        'verbose'         => 1,
);

# Store a complex data structure.
$queue->enqueue(
        {
                values => [ 1, 2, 3 ],
                data   => { key1 => 1, key2 => 2 },
        }
);

# Store a scalar, which must be passed by reference.
$queue->enqueue( \"Lorem ipsum dolor sit amet" );

# Process the queued elements one by one.
while ( my $queue_element = $queue->next() )
{
        # Skip elements that cannot be locked.
        next
                unless $queue_element->lock();

        eval {
                # Do some work
                process( $queue_element->{'email'} );
        };
        if ( $@ )
        {
                # Something failed, we clear the lock but don't delete the record in the
                # queue so that we can try again next time
                $queue_element->requeue();
        }
        else
        {
                # All good, remove definitively the element
                $queue_element->success();
        }
}

# Requeue items that have been locked for more than 6 hours
$queue->cleanup( 6 * 3600 );

🗄️ SUPPORTED DATABASES 🗄️

Right now this distribution supports, like, these ones:

SQLite
MySQL
PostgreSQL

And fr fr, if you need another database type supported, please contact me — I'm always glad to add extensions if you can help me with testing. teamwork makes the dream work 💜

🛠️ METHODS 🛠️

🌸 new() 🌸

Creates a brand new Queue::DBI object. Fresh out the box, iconic. ✨

my $queue = Queue::DBI->new(
        'queue_name'        => $queue_name,
        'database_handle'   => $dbh,
        'cleanup_timeout'   => 3600,
        'verbose'           => 1,
        'max_requeue_count' => 5,
);

# Custom table names (optional).
my $queue = Queue::DBI->new(
        'queue_name'                => $queue_name,
        'database_handle'           => $dbh,
        'cleanup_timeout'           => 3600,
        'verbose'                   => 1,
        'max_requeue_count'         => 5,
        'queues_table_name'         => $custom_queues_table_name,
        'queue_elements_table_name' => $custom_queue_elements_table_name,
);

Parameters, bestie — here's the whole list, don't skip any:

'queue_name' — Mandatory. This is the name of the queue that elements get added to and removed from. 🎀
'database handle' — Mandatory. It's a DBI object.
'cleanup_timeout' — Optional. Set it to an integer that represents a time in seconds, and the module will automatically make elements available again if they've been locked for longuer than that time. 💅
'verbose' — Optional. This controls how chatty the warnings in the code are. 0 shows no warning at all; 1 only gives you one-line warnings about the current operation; and 2 will also usually output the SQL queries that get performed. iykyk.
'max_requeue_count' — By default, Queue:::DBI will retrieve again the queue elements that were requeued, with no limit on how many times they've been requeued. Use this option to say how many times an element can be requeued before it gets ignored when retrieving elements. 🙈
'queues_table_name' — By default, Queue::DBI uses a table named 'queues' to store the queue definitions. This option lets you use your own name, if you want to support separate queuing systems or legacy systems.
'queue_elements_table_name' — By default, Queue::DBI uses a table named 'queue_elements' to store the queued data. This option lets you use your own name, if you want to support separate queuing systems or legacy systems.
'lifetime' — By default, Queue:::DBI will fetch elements regardless of how old they are. Use this option to specify how old (in seconds) an element can be and still be retrieved for processing. ⭐

🔑 get_queue_id() 🔑

Returns the queue ID that corresponds to the current queue object. Like a little name tag for your queue. 🎀

my $queue_id = $queue->get_queue_id();

🔢 count() 🔢

Returns the number of elements chillin' in the queue.

my $elements_count = $queue->count();

Optional parameter:

exclude_locked_elements — Excludes locked elements from the count. Default is 0.

my $unlocked_elements_count = $queue->count(
        exclude_locked_elements => 1
);

📥 enqueue() 📥

Adds a new element at the end of the current queue. It's giving "get in line, bestie." 🌈

# Store a scalar by passing its reference.
my $queue_element_id = $queue->enqueue( \$string );
my $queue_element_id = $queue->enqueue( \"string" );

# Store an array reference.
my $queue_element_id = $queue->enqueue( [ 1, 2, 3 ] );

# Store a hash reference.
my $queue_element_id = $queue->enqueue( { key => 123 } );

# Store a complex datastructure.
my $queue_element_id = $queue->enqueue(
        {
                values => [ 1, 2, 3 ],
                data   => { key1 => 1, key2 => 2 },
        }
);

So the data you pass should be a reference to a scalar, or a reference to a complex data structure — but you cannot pass a scalar directly, okay? Aside from that, there's no limitation on what kind of data you can store, because it gets serialized for storage in the database. slay. 💖

⏭️ next() ⏭️

Retrieves the next element from the queue and hands it to you as a Queue::DBI::Element object.

my $queue_element = $queue->next();

while ( my $queue_element = $queue->next() )
{
        # [...]
}

Also, for testing purposes, you can specify a list of IDs to use when trying to retrieve elements, using 'search_in_ids':

my $queue_item = $queue->next( 'search_in_ids' => [ 123, 124, 125 ] );

📦 retrieve_batch() 📦

Retrieves a batch of elements from the queue and returns them in an arrayref. Bulk era. 👑

This method requires an integer to be passed as a parameter, to say what the maximum size of the batch to be retrieved is.

my $queue_elements = $queue->retrieve_batch( 500 );

foreach ( @$queue_elements )
{
        # [...]
}

Also, for testing purposes, you can specify a list of IDs to use when trying to retrieve elements, using 'search_in_ids':

my $queue_items = $queue->retrieve_batch(
        10,
        'search_in_ids' => [ 123, 124, 125 ],
);

🆔 get_element_by_id() 🆔

Retrieves a queue element using a queue element ID, and it ignores any lock placed on that element. Rude? maybe. useful? absolutely. 💅

This method is mostly useful when you're doing a lock on an element and then calling success/requeue asynchroneously.

This method requires a queue element ID to be passed as parameter.

my $queue_element = $queue->get_element_by_id( 123456 );

🧹 cleanup() 🧹

Requeues items that have been locked for more than the time in seconds you specify as a parameter.

It returns the items that got requeued, so you can take some specific action on them. 🦋

my $elements = $queue->cleanup( $time_in_seconds );
foreach my $element ( @$elements )
{
        # $element is a Queue::DBI::Element object
}

🗑️ purge() 🗑️

Removes queue elements — permanently, caveat emptor! 😭 — based on how many times they've been requeued, or on how old they are. Then it returns the number of elements deleted.

# Remove permanently elements that have been requeued more than 10 times.
my $deleted_elements_count = $queue->purge( max_requeue_count => 10 );

# Remove permanently elements that were created over an hour ago.
my $deleted_elements_count = $queue->purge( lifetime => 3600 );

Important: locked elements are not purged, even if they match the criteria — because they're presumed to be currently in process, and purging them would create unexpected failures in the application that's processing them. So like, don't. 🫶

Also note that max_requeue_count and lifetime cannot be combined. Pick a lane, bestie.

✨ ACCESSORS ✨

These are the lil getters and setters that let you peek at and poke the queue's settings, bestie. No cap. 💅

get_max_requeue_count()

Okay so this one tells you how many times an element is allowed to get requeued before it just gets ignored when you're pulling elements out. Like, "you've been bounced back too many times, we're not picking you up anymore" energy. 🚫

my $max_requeue_count = $queue->get_max_requeue_count();

set_max_requeue_count()

And this is the one where you set that number, queen. Set it to undef if you wanna disable the limit entirely — no ceiling, no rules, main character freedom. 🦋

# Don't keep pulling the element if it has been requeued more than 5 times.
$queue->set_max_requeue_count( 5 );+

# Retry without limit.
$queue->set_max_requeue_count( undef );

get_lifetime()

Returns how old an element can be before the queue is like "nope, too ancient, ignoring it" when retrieving elements. ⏳

# Find how old an element can be before the queue will stop retrieving it.
my $lifetime = $queue->get_lifetime();

set_lifetime()

Set how old an element can be before it gets ignored at retrieval time. Bestie, this is literally the age cutoff. 🎀

Set it to undef to reset Queue::DBI back to its default behavior of retrieving elements without any time limit.

# Don't pull queue elements that are more than an hour old.
$queue->set_lifetime( 3600 );

# Pull elements without time limit.
$queue->set_lifetime( undef );

get_verbose()

Returns the verbosity level — which the module uses to decide when and what kind of debugging statements / information should be warned out. 🗣️

Peep set_verbose() for the possible values this function can hand back to you.

warn 'Verbose' if $queue->get_verbose();

warn 'Very verbose' if $queue->get_verbose() > 1;

set_verbose()

Controls the verbosity of the warnings in the code, periodt:

0 will not display any warning;
1 will only give one line warnings about the current operation;
2 will also usually output the SQL queries performed.

$queue->set_verbose(1); # turn on verbose information

$queue->set_verbose(2); # be extra verbose

$queue->set_verbose(0); # quiet now!

🔧 INTERNAL METHODS 🔧

These are the behind-the-scenes girlies — internal, so like, you can touch them but they're doing their own thing. ✨

freeze()

Serializes an element so it can be stored in a SQL text column. It's giving "shrink it down and stash it". 🧊

my $frozen_data = $queue->freeze( $data );

thaw()

The glow-up reversal: deserializes an element that was stored in a SQL text column. 🌸

my $thawed_data = $queue->thaw( $frozen_data );

⚠️ DEPRECATED METHODS ⚠️

Bestie, these are the old ones. They still exist, but they're giving expired energy — please migrate, okay? 🙈

create_tables()

Please use create_tables() in Queue::DBI::Admin instead. 👑

Here's an example that shows how to refactor your call to this deprecated function:

# Load the admin module.
use Queue::DBI::Admin;

# Create the object which will allow managing the queues.
my $queues_admin = Queue::DBI::Admin->new(
    database_handle => $dbh,
);

# Create the tables required by Queue::DBI to store the queues and data.
$queues_admin->create_tables(
    drop_if_exist => $boolean,
);

lifetime()

Please use get_lifetime() and set_lifetime() instead.

verbose()

Please use get_verbose() and set_verbose() instead.

max_requeue_count()

Please use get_max_requeue_count() and set_max_requeue_count() instead.

🔧 INTERNAL METHODS 🔧

(Yes, again — the manpage said it twice and I'm not about to edit the queen's work. 💅)

get_dbh()

Returns the database handle used for this queue.

my $dbh = $queue->get_dbh();

get_queues_table_name()

Returns the name of the table used to store queue definitions.

my $queues_table_name = $queue->get_queues_table_name();

get_queue_elements_table_name()

Returns the name of the table used to store queue definitions.

my $queue_elements_table_name = $queue->get_queue_elements_table_name();

🐛 BUGS 🐛

Please report any bugs or feature requests through the web interface at <https://github.com/guillaumeaubert/Queue-DBI/issues/new>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. 🫶 (yes the notifications are automatic, we love a closed loop 💖)

🆘 SUPPORT 🆘

You can find documentation for this module with the perldoc command.

perldoc Queue::DBI

You can also look for information at:

GitHub's request tracker

<https://github.com/guillaumeaubert/Queue-DBI/issues>

AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Queue-DBI>

CPAN Ratings

<http://cpanratings.perl.org/d/Queue-DBI>

MetaCPAN

<https://metacpan.org/release/Queue-DBI>

👑 AUTHOR 👑

Guillaume Aubert <https://metacpan.org/author/AUBERTG>, "<aubertg at cpan.org>".

🌈 ACKNOWLEDGEMENTS 🌈

I originally developed this project for ThinkGeek (<http://www.thinkgeek.com/>). Thanks for allowing me to open-source it! 🫶✨

📜 COPYRIGHT & LICENSE 📜

This code is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE file for more details. 🚨 (yes bestie, that's the real disclaimer, no cap, read it fr fr)

That's a wrap, babes! 💖 This page was served up by perl v5.42.0 on 2025-07-25, and it's Queue::DBI(3pm) — go forth and queue responsibly. Slay. 💅✨

📦 where this page comes from

fedora 43: perl-Queue-DBI 2.7.0-26.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms