The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Queue-DBI-v2.5.3
River stage zero No dependents
8 ++
/ Queue::DBI::Admin

NAME

Queue::DBI::Admin - Manage Queue::DBI queues.

VERSION

Version 2.5.3

SYNOPSIS

        use Queue::DBI::Admin;

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

        # Check if the tables required by Queue::DBI exist.
        if ( !$queues_admin->has_tables() )
        {
                # Create the tables required by Queue::DBI to store the queues and data.
                $queues_admin->create_tables();
        }

        # Create a new queue.
        my $queue = $queues_admin->create_queue( $queue_name );

        # Test if a queue exists.
        if ( $queues_admin->has_queue( $queue_name ) )
        {
                ...
        }

        # Retrieve a queue.
        my $queue = $queues_admin->retrieve_queue( $queue_name );

        # Delete a queue.
        $queues_admin->delete_queue( $queue_name );

SUPPORTED DATABASES

This distribution currently supports:

  • SQLite

  • MySQL

  • PostgreSQL

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.

QUEUES ADMINISTRATION METHODS

new()

Create a new Queue::DBI::Admin object.

        my $queues_admin = Queue::DBI::Admin->new(
                database_handle => $database_handle,
        );

The 'database_handle' parameter is mandatory and must correspond to a DBI connection handle object.

Optional parameters:

  • queues_table_name

    By default, Queue::DBI uses a table named queues to store the queue definitions. This allows using 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 allows using your own name, if you want to support separate queuing systems or legacy systems.

        my $queues_admin = Queue::DBI::Admin->new(
                database_handle           => $database_handle,
                queues_table_name         => $custom_queues_table_name,
                queue_elements_table_name => $custom_queue_elements_table_name,
        );

create_queue()

Create a new queue.

        $queues_admin->create_queue( $queue_name );

has_queue()

Test if a queue exists.

        if ( $queues_admin->has_queue( $queue_name ) )
        {
                ...
        }

retrieve_queue()

Retrieve a queue.

        my $queue = $queues_admin->retrieve_queue( $queue_name );

        # See Queue::DBI->new() for all the available options.
        my $queue = $queues_admin->retrieve_queue(
                $queue_name,
                'cleanup_timeout'   => 3600,
                'verbose'           => 1,
                'max_requeue_count' => 5,
        );

delete_queue()

Delete a queue and all associated data, permanently. Use this function at your own risk!

        $queues_admin->delete_queue( $queue_name );

DATABASE SETUP METHODS

has_tables()

Determine if the tables required for Queue::DBI to operate exist.

        my $tables_exist = $queues_admin->has_tables();

This method returns 1 if all tables exist, 0 if none exist, and croaks with more information if some tables are missing or if the mandatory fields on some of the tables are missing.

create_tables()

Create the tables required by Queue::DBI to store the queues and data.

        $queues_admin->create_tables(
                drop_if_exist => $boolean,
        );

By default, it won't drop any table but you can force that by setting 'drop_if_exist' to 1. See drop_tables() for more information on how tables are dropped.

drop_tables()

Drop the tables used to store the queues and queue data.

Warning: there is no undo for this operation. Make sure you really want to drop the tables before using this method.

        $queues_admin->drop_tables();

Note: due to foreign key constraints, the tables are dropped in the reverse order in which they are created.

INTERNAL METHODS

get_database_handle()

Return the database handle associated with the Queue::DBI::Admin object.

        my $database_handle = $queue->get_database_handle();

get_queues_table_name()

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

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

get_queue_elements_table_name()

Return the name of the table used to store queue elements.

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

get_quoted_queues_table_name()

Return the name of the table used to store queue definitions, quoted for inclusion in SQL statements.

        my $quoted_queues_table_name = $queues_admin->get_quoted_queues_table_name();

get_quoted_queue_elements_table_name()

Return the name of the table used to store queue elements, quoted for inclusion in SQL statements.

        my $quoted_queue_elements_table_name = $queues_admin->get_quoted_queue_elements_table_name();

assert_database_type_supported()

Assert (i.e., die on failure) whether the database type specified by the database handle passed to new() is supported or not.

        my $database_type = $queues_admin->assert_database_type_supported();

Note: the type of the database handle associated with the current object is returned when it is supported.

get_database_type()

Return the database type corresponding to the database handle associated with the Queue::DBI::Admin object.

        my $database_type = $queues_admin->get_database_type();

has_table()

Return if a table required by Queue::DBI to operate exists.

        my $has_table = $queues_admin->has_table( $table_type );

Valid table types are:

  • 'queues'

  • 'queue_elements'

has_mandatory_fields()

Return if a table required by Queue::DBI has the mandatory fields.

        my $has_mandatory_fields = $queues_admin->has_mandatory_fields( $table_type );

Valid table types are:

  • 'queues'

  • 'queue_elements'

assert_tables_verified()

Assert that the tables exist and are defined correctly.

        $queues_admin->assert_tables_verified();

Note that this will perform the check only once per Queue::DBI::Admin object, as this is an expensive check that would otherwise slow down the methods that use it.

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.

SUPPORT

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

        perldoc Queue::DBI::Admin

You can also look for information at:

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

ACKNOWLEDGEMENTS

Thanks to Sergey Bond for suggesting this administration module to extend and complete the features offered by Queue::DBI.

COPYRIGHT & LICENSE

Copyright 2009-2014 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 http://www.gnu.org/licenses/