View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Guillaume Aubert > Queue-DBI-2.5.2 > Queue::DBI



Annotate this POD


View/Report Bugs
Module Version: v2.5.2   Source   Latest Release: Queue-DBI-v2.7.0


Queue::DBI - A queueing module with an emphasis on safety, using DBI as a storage system for queued data.


Version 2.5.2


This module allows you to safely use a queueing system by preventing backtracking, infinite loops and data loss.

An emphasis of this distribution is to provide an extremely reliable dequeueing mechanism without having to use transactions.

        use Queue::DBI;
        my $queue = Queue::DBI->new(
                'queue_name'      => $queue_name,
                'database_handle' => $dbh,
                'cleanup_timeout' => 3600,
                'verbose'         => 1,
        $queue->enqueue( $data );
        while ( my $queue_element = $queue->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
                        # All good, remove definitively the element
        # Requeue items that have been locked for more than 6 hours
        $queue->cleanup( 6 * 3600 );


This distribution currently supports:

Please contact me if you need support for another database type, I'm always glad to add extensions if you can help me with testing.



Create a new Queue::DBI object.

        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,



Returns the queue ID corresponding to the current queue object.

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


Returns the number of elements in the queue.

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

Optional parameter:

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


Adds a new element at the end of the current queue.

        my $queue_element_id = $queue->enqueue( $data );

The data passed can be a scalar or a reference to a complex data structure. There is no limitation on the type of data that can be stored as it is serialized for storage in the database.


Retrieves the next element from the queue and returns it in the form of a Queue::DBI::Element object.

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

Additionally, for testing purposes, a list of IDs to use when trying to retrieve elements can be specified using 'search_in_ids':

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


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

This method requires an integer to be passed as parameter to indicate the maximum size of the batch to be retrieved.

        my $queue_elements = $queue->retrieve_batch( 500 );
        foreach ( @$queue_elements )
                # [...]

Additionally, for testing purposes, a list of IDs to use when trying to retrieve elements can be specified using 'search_in_ids':

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


Retrieves a queue element using a queue element ID, ignoring any lock placed on that element.

This method is mostly useful when 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 );


Requeue items that have been locked for more than the time in seconds specified as parameter.

Returns the items requeued so that a specific action can be taken on them.

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


Remove (permanently, caveat emptor!) queue elements based on how many times they've been requeued or how old they are, and return 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, as they are presumed to be currently in process and purging them would create unexpected failures in the application processing them.

Also note that max_requeue_count and lifetime cannot be combined.



Return how many times an element can be requeued before it is ignored when retrieving elements.

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


Set the number of time an element can be requeued before it is ignored when retrieving elements. Set it to undef to disable the limit.

        # 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 );


Return how old an element can be before it is ignored when retrieving elements.

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


Set how old an element can be before it is ignored when retrieving elements.

Set it to undef to reset Queue::DBI back to its default behavior of retrieving elements without 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 );


Return the verbosity level, which is used in the module to determine when and what type of debugging statements / information should be warned out.

See set_verbose() for the possible values this function can return.

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


Control the verbosity of the warnings in the code:

        $queue->set_verbose(1); # turn on verbose information
        $queue->set_verbose(2); # be extra verbose
        $queue->set_verbose(0); # quiet now!



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

Here is 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.
                drop_if_exist => $boolean,


Please use get_lifetime() and set_lifetime() instead.


Please use get_verbose() and set_verbose() instead.


Please use get_max_requeue_count() and set_max_requeue_count() instead.



Returns the database handle used for this queue.

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


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

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


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

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


Guillaume Aubert, <aubertg at>.


Please report any bugs or feature requests through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


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

        perldoc Queue::DBI

You can also look for information at:


Thanks to ThinkGeek ( and its corporate overlords at Geeknet (, for footing the bill while I write code for them!

Thanks to Jacob Rose <jacob at>, who wrote the first queueing module at ThinkGeek and whose work provided the inspiration to write this full-fledged queueing system.

Thanks to Jamie McCarthy for the locking mechanism improvements in version 1.1.0.

Thanks to Sergey Bond for suggesting many features added in version 1.8.x (lifetime constraint, purge() function, get/set functions cleanup).


Copyright 2009-2013 Guillaume Aubert.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

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 GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see

syntax highlighting: