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

NAME

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

VERSION

Version 2.5.2

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.

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

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:

ACKNOWLEDGEMENTS

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

COPYRIGHT & LICENSE

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