1Queue::DBI::Admin(3)  User Contributed Perl Documentation Queue::DBI::Admin(3)
2
3
4

NAME

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

VERSION

9       Version 2.7.0
10

SYNOPSIS

12               use Queue::DBI::Admin;
13
14               # Create the object which will allow managing the queues.
15               my $queues_admin = Queue::DBI::Admin->new(
16                       database_handle => $dbh,
17               );
18
19               # Check if the tables required by Queue::DBI exist.
20               if ( !$queues_admin->has_tables() )
21               {
22                       # Create the tables required by Queue::DBI to store the queues and data.
23                       $queues_admin->create_tables();
24               }
25
26               # Create a new queue.
27               my $queue = $queues_admin->create_queue( $queue_name );
28
29               # Test if a queue exists.
30               if ( $queues_admin->has_queue( $queue_name ) )
31               {
32                       ...
33               }
34
35               # Retrieve a queue.
36               my $queue = $queues_admin->retrieve_queue( $queue_name );
37
38               # Delete a queue.
39               $queues_admin->delete_queue( $queue_name );
40

SUPPORTED DATABASES

42       This distribution currently supports:
43
44       •   SQLite
45
46       •   MySQL
47
48       •   PostgreSQL
49
50       Please contact me if you need support for another database type, I'm
51       always glad to add extensions if you can help me with testing.
52

QUEUES ADMINISTRATION METHODS

54   new()
55       Create a new Queue::DBI::Admin object.
56
57               my $queues_admin = Queue::DBI::Admin->new(
58                       database_handle => $database_handle,
59               );
60
61       The 'database_handle' parameter is mandatory and must correspond to a
62       DBI connection handle object.
63
64       Optional parameters:
65
66       •   queues_table_name
67
68           By default, Queue::DBI uses a table named queues to store the queue
69           definitions. This allows using your own name, if you want to
70           support separate queuing systems or legacy systems.
71
72       •   queue_elements_table_name
73
74           By default, Queue::DBI uses a table named queue_elements to store
75           the queued data. This allows using your own name, if you want to
76           support separate queuing systems or legacy systems.
77
78               my $queues_admin = Queue::DBI::Admin->new(
79                       database_handle           => $database_handle,
80                       queues_table_name         => $custom_queues_table_name,
81                       queue_elements_table_name => $custom_queue_elements_table_name,
82               );
83
84   create_queue()
85       Create a new queue.
86
87               $queues_admin->create_queue( $queue_name );
88
89   has_queue()
90       Test if a queue exists.
91
92               if ( $queues_admin->has_queue( $queue_name ) )
93               {
94                       ...
95               }
96
97   retrieve_queue()
98       Retrieve a queue.
99
100               my $queue = $queues_admin->retrieve_queue( $queue_name );
101
102               # See Queue::DBI->new() for all the available options.
103               my $queue = $queues_admin->retrieve_queue(
104                       $queue_name,
105                       'cleanup_timeout'   => 3600,
106                       'verbose'           => 1,
107                       'max_requeue_count' => 5,
108               );
109
110   delete_queue()
111       Delete a queue and all associated data, permanently. Use this function
112       at your own risk!
113
114               $queues_admin->delete_queue( $queue_name );
115

DATABASE SETUP METHODS

117   has_tables()
118       Determine if the tables required for Queue::DBI to operate exist.
119
120               my $tables_exist = $queues_admin->has_tables();
121
122       This method returns 1 if all tables exist, 0 if none exist, and croaks
123       with more information if some tables are missing or if the mandatory
124       fields on some of the tables are missing.
125
126   create_tables()
127       Create the tables required by Queue::DBI to store the queues and data.
128
129               $queues_admin->create_tables(
130                       drop_if_exist => $boolean,
131               );
132
133       By default, it won't drop any table but you can force that by setting
134       'drop_if_exist' to 1. See drop_tables() for more information on how
135       tables are dropped.
136
137   drop_tables()
138       Drop the tables used to store the queues and queue data.
139
140       Warning: there is no undo for this operation. Make sure you really want
141       to drop the tables before using this method.
142
143               $queues_admin->drop_tables();
144
145       Note: due to foreign key constraints, the tables are dropped in the
146       reverse order in which they are created.
147

INTERNAL METHODS

149   get_database_handle()
150       Return the database handle associated with the Queue::DBI::Admin
151       object.
152
153               my $database_handle = $queue->get_database_handle();
154
155   get_queues_table_name()
156       Return the name of the table used to store queue definitions.
157
158               my $queues_table_name = $queues_admin->get_queues_table_name();
159
160   get_queue_elements_table_name()
161       Return the name of the table used to store queue elements.
162
163               my $queue_elements_table_name = $queues_admin->get_queue_elements_table_name();
164
165   get_quoted_queues_table_name()
166       Return the name of the table used to store queue definitions, quoted
167       for inclusion in SQL statements.
168
169               my $quoted_queues_table_name = $queues_admin->get_quoted_queues_table_name();
170
171   get_quoted_queue_elements_table_name()
172       Return the name of the table used to store queue elements, quoted for
173       inclusion in SQL statements.
174
175               my $quoted_queue_elements_table_name = $queues_admin->get_quoted_queue_elements_table_name();
176
177   assert_database_type_supported()
178       Assert (i.e., die on failure) whether the database type specified by
179       the database handle passed to new() is supported or not.
180
181               my $database_type = $queues_admin->assert_database_type_supported();
182
183       Note: the type of the database handle associated with the current
184       object is returned when it is supported.
185
186   get_database_type()
187       Return the database type corresponding to the database handle
188       associated with the Queue::DBI::Admin object.
189
190               my $database_type = $queues_admin->get_database_type();
191
192   has_table()
193       Return if a table required by Queue::DBI to operate exists.
194
195               my $has_table = $queues_admin->has_table( $table_type );
196
197       Valid table types are:
198
199       •   'queues'
200
201       •   'queue_elements'
202
203   has_mandatory_fields()
204       Return if a table required by Queue::DBI has the mandatory fields.
205
206               my $has_mandatory_fields = $queues_admin->has_mandatory_fields( $table_type );
207
208       Valid table types are:
209
210       •   'queues'
211
212       •   'queue_elements'
213
214   assert_tables_verified()
215       Assert that the tables exist and are defined correctly.
216
217               $queues_admin->assert_tables_verified();
218
219       Note that this will perform the check only once per Queue::DBI::Admin
220       object, as this is an expensive check that would otherwise slow down
221       the methods that use it.
222

BUGS

224       Please report any bugs or feature requests through the web interface at
225       <https://github.com/guillaumeaubert/Queue-DBI/issues/new>.  I will be
226       notified, and then you'll automatically be notified of progress on your
227       bug as I make changes.
228

SUPPORT

230       You can find documentation for this module with the perldoc command.
231
232               perldoc Queue::DBI::Admin
233
234       You can also look for information at:
235
236       •   GitHub's request tracker
237
238           <https://github.com/guillaumeaubert/Queue-DBI/issues>
239
240       •   AnnoCPAN: Annotated CPAN documentation
241
242           <http://annocpan.org/dist/Queue-DBI>
243
244       •   CPAN Ratings
245
246           <http://cpanratings.perl.org/d/Queue-DBI>
247
248       •   MetaCPAN
249
250           <https://metacpan.org/release/Queue-DBI>
251

AUTHOR

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

ACKNOWLEDGEMENTS

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

COPYRIGHT & LICENSE

261       Copyright 2009-2017 Guillaume Aubert.
262
263       This code is free software; you can redistribute it and/or modify it
264       under the same terms as Perl 5 itself.
265
266       This program is distributed in the hope that it will be useful, but
267       WITHOUT ANY WARRANTY; without even the implied warranty of
268       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE
269       file for more details.
270
271
272
273perl v5.36.0                      2023-01-20              Queue::DBI::Admin(3)