1POE::Component::SimpleDUBsIe(r3pCmo)ntributed Perl DocumPeOnEt:a:tCioomnponent::SimpleDBI(3pm)
2
3
4

NAME

6       POE::Component::SimpleDBI - Asynchronous non-blocking DBI calls in POE
7       made simple
8

VERSION

10         This document describes v1.31 of POE::Component::SimpleDBI - released November 05, 2014 as part of POE-Component-SimpleDBI.
11

SYNOPSIS

13               use POE;
14               use POE::Component::SimpleDBI;
15
16               # Create a new session with the alias we want
17               POE::Component::SimpleDBI->new( 'SimpleDBI' ) or die 'Unable to create the DBI session';
18
19               # Create our own session to communicate with SimpleDBI
20               POE::Session->create(
21                       inline_states => {
22                               _start => sub {
23                                       # Tell SimpleDBI to connect
24                                       $_[KERNEL]->post( 'SimpleDBI', 'CONNECT',
25                                               'DSN'           =>      'DBI:mysql:database=foobaz;host=192.168.1.100;port=3306',
26                                               'USERNAME'      =>      'FooBar',
27                                               'PASSWORD'      =>      'SecretPassword',
28                                               'EVENT'         =>      'conn_handler',
29                                       );
30
31                                       # Execute a query and return number of rows affected
32                                       $_[KERNEL]->post( 'SimpleDBI', 'DO',
33                                               'SQL'           =>      'DELETE FROM FooTable WHERE ID = ?',
34                                               'PLACEHOLDERS'  =>      [ qw( 38 ) ],
35                                               'EVENT'         =>      'deleted_handler',
36                                               'INSERT_ID'     =>      0,
37                                       );
38
39                                       # Retrieve one row of information
40                                       $_[KERNEL]->post( 'SimpleDBI', 'SINGLE',
41                                               'SQL'           =>      'Select * from FooTable LIMIT 1',
42                                               'EVENT'         =>      'success_handler',
43                                               'BAGGAGE'       =>      'Some Stuff I want to keep!',
44                                       );
45
46                                       # We want many rows of information + get the query ID so we can delete it later
47                                       # Furthermore, disable prepare_cached on this query
48                                       my $id = $_[KERNEL]->call( 'SimpleDBI', 'MULTIPLE',
49                                               'SQL'           =>      'SELECT foo, baz FROM FooTable2 WHERE id = ?',
50                                               'PLACEHOLDERS'  =>      [ qw( 53 ) ],
51                                               'EVENT'         =>      'multiple_handler',
52                                               'PREPARE_CACHED'=>      0,
53                                       );
54
55                                       # Quote something and send it to another session
56                                       $_[KERNEL]->post( 'SimpleDBI', 'QUOTE',
57                                               'SQL'           =>      'foo$*@%%sdkf"""',
58                                               'SESSION'       =>      'OtherSession',
59                                               'EVENT'         =>      'quote_handler',
60                                       );
61
62                                       # Changed our mind!
63                                       $_[KERNEL]->post( 'SimpleDBI', 'Delete_Query', $id );
64
65                                       # 3 ways to shutdown
66
67                                       # This will let the existing queries finish, then shutdown
68                                       $_[KERNEL]->post( 'SimpleDBI', 'shutdown' );
69
70                                       # This will terminate when the event traverses
71                                       # POE's queue and arrives at SimpleDBI
72                                       $_[KERNEL]->post( 'SimpleDBI', 'shutdown', 'NOW' );
73
74                                       # Even QUICKER shutdown :)
75                                       $_[KERNEL]->call( 'SimpleDBI', 'shutdown', 'NOW' );
76                               },
77
78                               # Define your request handlers here
79                               'quote_handler' =>      \&FooHandler,
80                               # And so on
81                       },
82               );
83

DESCRIPTION

85       This module simplifies DBI usage in POE's multitasking world.
86
87       This module is a breeze to use, you'll have DBI calls in your POE
88       program up and running in only a few seconds of setup.
89
90       This module does what XML::Simple does for the XML world.
91
92       This module works its magic by creating a new session with POE, then
93       spawning off a child process to do the "heavy" lifting. That way, your
94       main POE process can continue servicing other clients.  Queries are put
95       into a queue, and processed one at a time.
96
97       The standard way to use this module is to do this:
98
99               use POE;
100               use POE::Component::SimpleDBI;
101
102               POE::Component::SimpleDBI->new( ... );
103
104               POE::Session->create( ... );
105
106               POE::Kernel->run();
107
108   Starting SimpleDBI
109       To start SimpleDBI, just call it's new method:
110
111               POE::Component::SimpleDBI->new( 'ALIAS' );
112
113       This method will die on error or return success.
114
115       NOTE: The act of starting/stopping SimpleDBI fires off _child events,
116       read the POE documentation on what to do with them :)
117
118       This constructor accepts only 3 arguments.
119
120       Alias
121
122       This sets the session alias in POE.
123
124       The default is "SimpleDBI".
125
126       PREPARE_CACHED
127
128       This sets the global PREPARE_CACHED setting. This is a boolean value.
129
130               POE::Component::SimpleDBI->new( 'ALIAS', 0 );
131
132       The default is enabled.
133
134       SYNCHRONOUS_MODE
135
136       This disables the fork() that the subprocess does. Use this only if you
137       are having issues with the backend and want to debug the database
138       without dealing with multiprocess issues.
139
140               POE::Component::SimpleDBI->new( 'ALIAS', 1, 1 );
141
142       The default is disabled.
143
144   Commands
145       There are a few commands you can trigger in SimpleDBI. They are
146       triggered via $_[KERNEL]->post( ... );
147
148       ID
149
150       All of the commands except for Delete_Query and shutdown return an id.
151       To get them, do this:      my $id = $_[KERNEL]->call( 'SimpleDBI', ...
152       );
153
154       Afterwards, the id can be used to delete queries, look at Delete_Query
155       for more information.
156
157       Argument errors
158
159       All of the commands validate their arguments, and if an error happens (
160       missing argument, etc ), they will do either:      - return undef and
161       forget that your request even existed      - post to the SESSION/EVENT
162       with ERROR present in the data           NOTE: The data will not have
163       an ID key present
164
165       Explanation of DO/SINGLE/MULTIPLE/QUOTE arguments
166
167       They are passed in via the $_[KERNEL]->post( ... );
168
169       NOTE: Capitalization is very important!
170
171       "SQL"
172           This is the actual SQL line you want SimpleDBI to execute.  You can
173           put in placeholders, this module supports them.
174
175       "PLACEHOLDERS"
176           This is an array of placeholders.
177
178           You can skip this if your query does not utilize it.
179
180       "SESSION"
181           This is the session that will get the result
182
183           You can skip this, it defaults to the sending session
184
185       "EVENT"
186           This is the event, triggered whenever a query finished.
187
188           It will get a hash in ARG0, consult the specific queries on what
189           you will get.
190
191           NOTE: If the key 'ERROR' exists in the hash, then it will contain
192           the error string.
193
194       "BAGGAGE"
195           This is a special argument, you can "attach" any kind of baggage to
196           a query.  The baggage will be kept by SimpleDBI and returned to the
197           Event handler intact.
198
199           This is good for storing data associated with a query like a client
200           object, etc.
201
202           You can skip this if your query does not utilize it.
203
204       "PREPARE_CACHED"
205           This was added recently, to override SimpleDBI's default behavior
206           of using the $dbh->prepare_cached() function. Setting this to false
207           will use $dbh->prepare() instead.
208
209           Some users reported problems with PostgreSQL. After investigation,
210           this turned out to be some bizarre OID caching issues when the
211           table was updated while the connection is alive.  The quick work-
212           around is to reconnect to the database, but this was not a "sane"
213           solution.
214
215           This is a simple boolean value, and if this argument does not
216           exist, SimpleDBI will use the global setting when calling new().
217
218       "INSERT_ID"
219           This was added recently, to override SimpleDBI's default behavior
220           of using the $dbh->last_insert_id() function. Setting this to false
221           will disable retrieval of this value.
222
223           This is a simple boolean value, and if this argument does not
224           exist, SimpleDBI will default to true.
225
226       "CONNECT"
227
228       This tells SimpleDBI to connect to the database. NOTE: if we are
229       already connected, it will be a success ( SimpleDBI will not disconnect
230       then connect automatically ). Accepted arguments:
231
232               DSN             ->      The DBI DSN string, consult the DBI docs on what this is
233               USERNAME        ->      The username for the connection
234               PASSWORD        ->      The password for the connection
235               SESSION         ->      The session to send the results
236               EVENT           ->      The event to send the results
237               NOW             ->      Tells SimpleDBI to bypass the queue and connect NOW!
238               CLEAR           ->      Tells SimpleDBI to clear the queue and connect NOW!
239               AUTO_COMMIT     ->      The boolean value we will pass to DBI->connect ( defaults to true )
240               CACHEDKIDS      ->      Controls the method to cache prepare_cached queries, an arrayref ( defaults to undef )
241               BAGGAGE         ->      Any extra data to keep associated with this query ( SimpleDBI will not touch it )
242
243       NOTE: if the DSN/USERNAME/PASSWORD/SESSION/EVENT does not exist,
244       SimpleDBI assumes you wanted to use the old connection and will use the
245       cached values ( if you told it to DISCONNECT ). Here's an example on
246       how to trigger this event:
247
248               $_[KERNEL]->post( 'SimpleDBI', 'CONNECT',
249                       'DSN'           =>      'DBI:mysql:database=foobaz;host=192.168.1.100;port=3306',
250                       'USERNAME'      =>      'MyUser',
251                       'PASSWORD'      =>      'MyPassword',
252                       'EVENT'         =>      'conn_handler',
253                       'NOW'           =>      1,
254               );
255
256       The NOW/CLEAR arguments are special, they will tell SimpleDBI to bypass
257       the request queue and connect NOW...  The CLEAR argument will also
258       delete all the requests waiting in the queue, they will get an ERROR
259       result.  They both default to false, supply a boolean value to turn
260       them on. The Event handler will get a hash in ARG0:
261
262               {
263                       'ERROR'         =>      exists only if an error occured
264                       'GONE'          =>      exists only if the server was disconnected and the reconnect failed
265                       'ACTION'        =>      'CONNECT'
266                       'ID'            =>      ID of the Query
267                       'EVENT'         =>      The event the query will respond to
268                       'SESSION'       =>      The session the query will respond to
269               }
270
271               # NOTE: You can do nifty things like this. They all will be executed in the right order!
272               $_[KERNEL]->post( 'SimpleDBI', 'CONNECT', 'DSN' => 'DBI:mysql:...', ... );
273               $_[KERNEL]->post( 'SimpleDBI', 'DO', ... );
274               $_[KERNEL]->post( 'SimpleDBI', 'SINGLE', ... );
275               $_[KERNEL]->post( 'SimpleDBI', 'DISCONNECT' );
276               $_[KERNEL]->post( 'SimpleDBI', 'CONNECT', 'DSN' => 'DBI:oracle:...', ... );
277               $_[KERNEL]->post( 'SimpleDBI', 'MULTIPLE', ... );
278               $_[KERNEL]->post( 'SimpleDBI', 'shutdown' );
279
280       As of 1.11 SimpleDBI now detects whether the backend lost the
281       connection to the database server. The backend will automatically
282       reconnect if it happens, but if that fails, an error will be sent to
283       the session/event specified here with an extra key: 'GONE'. In this
284       state SimpleDBI is deadlocked, any new queries will not be processed
285       until a CONNECT NOW event is issued! Keep in mind the SINGLE/etc
286       queries WILL NOT receive an error if this happens, the error goes
287       straight to the CONNECT handler to keep it simple!
288
289       As of 1.29 SimpleDBI added better control of the prepare_cached cache.
290       Some users reported that the subprocess' memory usage was leaking, and
291       in extreme cases reached several gigs! Upon investigation, it was not
292       SimpleDBI's fault but the way DBI works. What DBI does is cache the
293       statement handle from $dbh->prepare_cached in the $dbh handle. The
294       problem is that it stays around forever in the default implementation!
295       Perusing the DBI docs revealed that it was possible to tie this cache
296       to a custom cache module. So I've added the CACHEDKIDS argument, and
297       setting it to an arrayref will enable the behavior. Look at
298       <http://search.cpan.org/dist/DBI/DBI.pm#prepare_cached> for more
299       information. Here's an example:
300
301               $_[KERNEL]->post( 'SimpleDBI', 'CONNECT', ..., 'CACHEDKIDS' => [ 'Tie::Cache::LRU' ] );
302
303       The first element in the array is the module to use when tying the
304       cache. Any additional elements are passed to the module's constructor.
305       Please look at the docs for your favorite cache module! If users report
306       success with this, in a future version of SimpleDBI it might become the
307       default behavior. Keep in mind that this will be redundant if
308       PREPARE_CACHED == 0.
309
310       "DISCONNECT"
311
312       This tells SimpleDBI to disconnect from the database. NOTE: In the case
313       that a DISCONNECT is issued when we are not connected, it will still
314       succeed! Accepted arguments:
315
316               SESSION         ->      The session to send the results
317               EVENT           ->      The event to send the results
318               NOW             ->      Tells SimpleDBI to bypass the queue and disconnect NOW!
319               CLEAR           ->      Tells SimpleDBI to clear the queue and disconnect NOW!
320               BAGGAGE         ->      Any extra data to keep associated with this query ( SimpleDBI will not touch it )
321
322       Here's an example on how to trigger this event:
323
324               $_[KERNEL]->post( 'SimpleDBI', 'DISCONNECT',
325                       'EVENT'         =>      'disconn_handler',
326                       'NOW'           =>      1,
327               );
328
329       The NOW/CLEAR arguments are special, they will tell SimpleDBI to bypass
330       the request queue and connect NOW.  The CLEAR argument will also delete
331       all the requests waiting in the queue, they will get an ERROR result.
332       They both default to false, supply a boolean value to turn them on. The
333       Event handler will get a hash in ARG0:
334
335               {
336                       'ERROR'         =>      exists only if an error occured
337                       'ACTION'        =>      'DISCONNECT'
338                       'ID'            =>      ID of the Query
339                       'EVENT'         =>      The event the query will respond to
340                       'SESSION'       =>      The session the query will respond to
341               }
342
343               # BEWARE: There is the possibility of a deadlock! In this case, the DO/SINGLE queries will
344               # NEVER run until you issue a CONNECT with NOW enabled at the end!
345               $_[KERNEL]->post( 'SimpleDBI', 'CONNECT', ... );
346               $_[KERNEL]->post( 'SimpleDBI', 'MULTIPLE', ... );
347               $_[KERNEL]->post( 'SimpleDBI', 'DISCONNECT' );
348               $_[KERNEL]->post( 'SimpleDBI', 'DO', ... );
349               $_[KERNEL]->post( 'SimpleDBI', 'SINGLE', ... );
350               $_[KERNEL]->post( 'SimpleDBI', 'CONNECT' );
351
352       "QUOTE"
353
354       This simply sends off a string to be quoted, and gets it back. Accepted
355       arguments:
356
357               SESSION         ->      The session to send the results
358               EVENT           ->      The event to send the results
359               SQL             ->      The string to be quoted
360               BAGGAGE         ->      Any extra data to keep associated with this query ( SimpleDBI will not touch it )
361
362       Internally, it does something like this:
363
364               return $dbh->quote( $SQL );
365
366       Here's an example on how to trigger this event:
367
368               $_[KERNEL]->post( 'SimpleDBI', 'QUOTE',
369                       SQL => 'foo$*@%%sdkf"""',
370                       EVENT => 'quote_handler',
371               );
372
373       The Event handler will get a hash in ARG0:
374
375               {
376                       'ERROR'         =>      exists only if an error occured
377                       'ACTION'        =>      'QUOTE'
378                       'ID'            =>      ID of the Query
379                       'EVENT'         =>      The event the query will respond to
380                       'SESSION'       =>      The session the query will respond to
381                       'SQL'           =>      Original SQL inputted
382                       'RESULT'        =>      The quoted SQL
383                       'PLACEHOLDERS'  =>      Original placeholders ( may not exist if it was not provided )
384                       'BAGGAGE'       =>      whatever you set it to ( may not exist if it was not provided )
385               }
386
387       "DO"
388
389       This query is specialized for those queries where you
390       UPDATE/DELETE/INSERT/etc. THIS IS NOT FOR SELECT QUERIES!  Accepted
391       arguments:
392
393               SESSION         ->      The session to send the results
394               EVENT           ->      The event to send the results
395               SQL             ->      The string to be quoted
396               PLACEHOLDERS    ->      Any placeholders ( if needed )
397               BAGGAGE         ->      Any extra data to keep associated with this query ( SimpleDBI will not touch it )
398               PREPARE_CACHED  ->      Boolean value ( if needed )
399               INSERT_ID       ->      Boolean value ( if needed )
400
401       Internally, it does something like this:
402
403               $sth = $dbh->prepare_cached( $SQL );
404               $rows_affected = $sth->execute( $PLACEHOLDERS );
405               return $rows_affected;
406
407       Here's an example on how to trigger this event:
408
409               $_[KERNEL]->post( 'SimpleDBI', 'DO',
410                       SQL => 'DELETE FROM FooTable WHERE ID = ?',
411                       PLACEHOLDERS => [ 38 ],
412                       EVENT => 'deleted_handler',
413               );
414
415       The Event handler will get a hash in ARG0:
416
417               {
418                       'ERROR'         =>      exists only if an error occured
419                       'ACTION'        =>      'DO'
420                       'ID'            =>      ID of the Query
421                       'EVENT'         =>      The event the query will respond to
422                       'SESSION'       =>      The session the query will respond to
423                       'SQL'           =>      Original SQL inputted
424                       'RESULT'        =>      Scalar value of rows affected
425                       'PLACEHOLDERS'  =>      Original placeholders ( may not exist if it was not provided )
426                       'BAGGAGE'       =>      whatever you set it to ( may not exist if it was not provided )
427                       'INSERTID'      =>      The insert ID - using $dbh->last_insert_id( undef, undef, undef, undef ) [ defaults to undef ]
428               }
429
430       "SINGLE"
431
432       This query is specialized for those queries where you will get exactly
433       1 result back.      Accepted arguments:
434
435               SESSION         ->      The session to send the results
436               EVENT           ->      The event to send the results
437               SQL             ->      The string to be quoted
438               PLACEHOLDERS    ->      Any placeholders ( if needed )
439               BAGGAGE         ->      Any extra data to keep associated with this query ( SimpleDBI will not touch it )
440               PREPARE_CACHED  ->      Boolean value ( if needed )
441
442       Internally, it does something like this:
443
444               $sth = $dbh->prepare_cached( $SQL );
445               $sth->execute( $PLACEHOLDERS );
446               $result = $sth->fetchrow_hashref;
447               return $result;
448
449       Here's an example on how to trigger this event:
450
451               $_[KERNEL]->post( 'SimpleDBI', 'SINGLE',
452                       SQL => 'Select * from FooTable',
453                       EVENT => 'success_handler',
454                       SESSION => 'MySession',
455               );
456
457       The Event handler will get a hash in ARG0:
458
459               {
460                       'ERROR'         =>      exists only if an error occured
461                       'ACTION'        =>      'SINGLE'
462                       'ID'            =>      ID of the Query
463                       'EVENT'         =>      The event the query will respond to
464                       'SESSION'       =>      The session the query will respond to
465                       'SQL'           =>      Original SQL inputted
466                       'RESULT'        =>      Hash of columns - similar to fetchrow_hashref ( undef if no rows returned )
467                       'PLACEHOLDERS'  =>      Original placeholders ( may not exist if it was not provided )
468                       'BAGGAGE'       =>      whatever you set it to ( may not exist if it was not provided )
469               }
470
471       "MULTIPLE"
472
473       This query is specialized for those queries where you will get more
474       than 1 result back.
475
476       WARNING! The column names are all lowercased automatically! WARNING!
477
478       Accepted arguments:
479
480               SESSION         ->      The session to send the results
481               EVENT           ->      The event to send the results
482               SQL             ->      The string to be quoted
483               PLACEHOLDERS    ->      Any placeholders ( if needed )
484               BAGGAGE         ->      Any extra data to keep associated with this query ( SimpleDBI will not touch it )
485               PREPARE_CACHED  ->      Boolean value ( if needed )
486
487       Internally, it does something like this:
488
489               $sth = $dbh->prepare_cached( $SQL );
490               $sth->execute( $PLACEHOLDERS );
491               $sth->bind_columns( \( @$newdata{ @{ $sth->{'NAME_lc'} } } ) );
492               while ( $sth->fetch() ) {
493                       push( @results, { @$newdata } );
494               }
495               return \@results;
496
497       Here's an example on how to trigger this event:
498
499               $_[KERNEL]->post( 'SimpleDBI', 'MULTIPLE',
500                       SQL => 'SELECT foo, baz FROM FooTable2 WHERE id = ?',
501                       EVENT => 'multiple_handler',
502                       PLACEHOLDERS => [ 53 ],
503                       PREPARE_CACHED => 0,
504               );
505
506       The Event handler will get a hash in ARG0:
507
508               {
509                       'ERROR'         =>      exists only if an error occured
510                       'ACTION'        =>      'MULTIPLE'
511                       'ID'            =>      ID of the Query
512                       'EVENT'         =>      The event the query will respond to
513                       'SESSION'       =>      The session the query will respond to
514                       'SQL'           =>      Original SQL inputted
515                       'RESULT'        =>      Array of hash of columns - similar to array of fetchrow_hashref's ( undef if no rows returned )
516                       'PLACEHOLDERS'  =>      Original placeholders ( may not exist if it was not provided )
517                       'BAGGAGE'       =>      whatever you set it to ( may not exist if it was not provided )
518               }
519
520       "ATOMIC"
521
522       This query is specialized for those queries that you need to execute in
523       a transaction. You supply an array of SQL queries, and SimpleDBI will
524       execute them all in a transaction block. No need to worry about
525       AutoCommit, BEGIN, and END TRANSACTION!
526
527       You are supposed to pass an array of queries that normally would be
528       executed in a DO-style query. Again, you cannot execute SELECT queries
529       in this type of command! Currently there is no control over
530       prepare_cached for individual queries. It may be added in a future
531       release.
532
533       WARNING: It tripped me up on my testing when I realized this worked on
534       Postgres but not MySQL. I forgot that I was testing against MyISAM
535       tables, which doesn't support transactions! ( it works nicely on InnoDB
536       tables hah ) So, if this doesn't "behave" properly for you please check
537       your database tables! Accepted arguments:
538
539               SESSION         ->      The session to send the results
540               EVENT           ->      The event to send the results
541               SQL             ->      The array of SQL queries
542               PLACEHOLDERS    ->      The array of placeholders ( if needed ) [ this is an AoA - array of arrays! ]
543               BAGGAGE         ->      Any extra data to keep associated with this query ( SimpleDBI will not touch it )
544               PREPARE_CACHED  ->      Boolean value ( if needed ) [ for all of the queries! ]
545
546       Internally, it does something like this:
547
548               eval {
549                       $dbh->begin_work;
550                       for my $idx ( 0 .. $#array ) {
551                               if ( $prepare_cached ) {
552                                       $sth = $dbh->prepare_cached( $array[ $idx ] );
553                               } else {
554                                       $sth = $dbh->prepare( $array[ $idx ] );
555                               }
556                               if ( defined $PLACEHOLDERS[ $idx ] ) {
557                                       $sth->execute( $PLACEHOLDERS[ $idx ] );
558                               } else {
559                                       $sth->execute;
560                               }
561                               $sth->finish;
562                       }
563                       $dbh->commit;
564               };
565               if ( $@ ) {
566                       eval { $dbh->rollback };
567                       if ( $@ ) {
568                               return ROLLBACK_FAILURE;
569                       } else {
570                               return COMMIT_FAILURE;
571                       }
572               } else {
573                       return SUCCESS;
574               }
575
576       Here's an example on how to trigger this event:
577
578               $_[KERNEL]->post( 'SimpleDBI', 'ATOMIC',
579                       SQL => [
580                               'DELETE FROM FooTable WHERE ID = ?',
581                               'UPDATE FooTable SET baz = ? WHERE bar = ?',
582                       ],
583                       EVENT => 'atomic_handler',
584                       PLACEHOLDERS => [       [ 53 ],
585                                               [ 5, 86 ]
586                       ],
587               );
588
589       The Event handler will get a hash in ARG0:
590
591               {
592                       'ERROR'         =>      exists only if an error occured ( ROLLBACK_FAILURE or COMMIT_FAILURE with explanation )
593                       'ACTION'        =>      'ATOMIC'
594                       'ID'            =>      ID of the Query
595                       'EVENT'         =>      The event the query will respond to
596                       'SESSION'       =>      The session the query will respond to
597                       'SQL'           =>      Original SQL array inputted
598                       'RESULT'        =>      Either SUCCESS or in case of error, not exists
599                       'PLACEHOLDERS'  =>      Original placeholders ( may not exist if it was not provided )
600                       'BAGGAGE'       =>      whatever you set it to ( may not exist if it was not provided )
601               }
602
603       "Delete_Query"
604
605       Call this event if you want to delete a query via the ID. Returns:
606
607               undef if it wasn't able to find the ID
608               0 if the query is currently being processed
609               1 if the query was successfully deleted
610
611       Here's an example on how to trigger this event:
612
613               $_[KERNEL]->post( 'SimpleDBI', 'Delete_Query', $queryID );
614
615       IF you really want to know the status, execute a call on the event and
616       check the returned value.
617
618       "Clear_Queue"
619
620       This event will clear the entire queue except the running query, if
621       there is one.
622
623       You can also pass in one argument -> the error string to be used
624       instead of the default, 'Cleared the queue'
625
626       All the queries in the queue will return ERROR to their respective
627       sessions/events
628
629       "shutdown"
630
631       This will signal SimpleDBI to start the shutdown procedure. Without
632       arguments, SimpleDBI will wait for outstanding queries to complete
633       before killing it's session. You can also specify an argument to ignore
634       those queries and immediately halt:
635
636               $_[KERNEL]->post( 'SimpleDBI', 'shutdown', 'NOW' );
637
638       Due to the way POE's queue works, this shutdown event will take some
639       time to propagate POE's queue.  If you REALLY want to shut down
640       immediately, do this:
641
642               $_[KERNEL]->call( 'SimpleDBI', 'shutdown', 'NOW' );
643
644   SimpleDBI Notes
645       This module is very picky about capitalization!
646
647       All of the options are uppercase, to avoid confusion.
648
649       You can enable debugging mode by doing this:
650
651               sub POE::Component::SimpleDBI::DEBUG () { 1 }
652               use POE::Component::SimpleDBI;
653
654       Also, this module will try to keep the SubProcess alive.  if it dies,
655       it will open it again for a max of 5 retries.
656
657       You can override this behavior by doing this:
658
659               sub POE::Component::SimpleDBI::MAX_RETRIES () { 10 }
660               use POE::Component::SimpleDBI;
661
662       DBI attributes
663
664       Since SimpleDBI doesn't expose the DBI handle it might be an issue if
665       you need to set custom attributes.  Fear not for DBI already has a
666       standard mechanism for this: "connection attribute values" in
667       "#connect" in DBI. Here is an example to enable utf8 for a Postgres
668       database:
669
670               $_[KERNEL]->post( 'SimpleDBI', 'CONNECT',
671                       'DSN'           =>      'DBI:Pg(pg_enable_utf8=>1):host=foo;dbname=bar',
672                       ...
673               );
674

SEE ALSO

676       Please see those modules/websites for more information related to this
677       module.
678
679       •   DBI
680
681       •   POE::Component::DBIAgent
682
683       •   POE::Component::LaDBI
684
685       •   POE::Component::EasyDBI
686

SUPPORT

688   Perldoc
689       You can find documentation for this module with the perldoc command.
690
691         perldoc POE::Component::SimpleDBI
692
693   Websites
694       The following websites have more information about this module, and may
695       be of help to you. As always, in addition to those websites please use
696       your favorite search engine to discover more resources.
697
698       •   MetaCPAN
699
700           A modern, open-source CPAN search engine, useful to view POD in
701           HTML format.
702
703           <http://metacpan.org/release/POE-Component-SimpleDBI>
704
705       •   Search CPAN
706
707           The default CPAN search engine, useful to view POD in HTML format.
708
709           <http://search.cpan.org/dist/POE-Component-SimpleDBI>
710
711       •   RT: CPAN's Bug Tracker
712
713           The RT ( Request Tracker ) website is the default bug/issue
714           tracking system for CPAN.
715
716           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-SimpleDBI>
717
718       •   AnnoCPAN
719
720           The AnnoCPAN is a website that allows community annotations of Perl
721           module documentation.
722
723           <http://annocpan.org/dist/POE-Component-SimpleDBI>
724
725       •   CPAN Ratings
726
727           The CPAN Ratings is a website that allows community ratings and
728           reviews of Perl modules.
729
730           <http://cpanratings.perl.org/d/POE-Component-SimpleDBI>
731
732       •   CPAN Forum
733
734           The CPAN Forum is a web forum for discussing Perl modules.
735
736           <http://cpanforum.com/dist/POE-Component-SimpleDBI>
737
738       •   CPANTS
739
740           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
741           of a distribution.
742
743           <http://cpants.cpanauthors.org/dist/overview/POE-Component-SimpleDBI>
744
745       •   CPAN Testers
746
747           The CPAN Testers is a network of smokers who run automated tests on
748           uploaded CPAN distributions.
749
750           <http://www.cpantesters.org/distro/P/POE-Component-SimpleDBI>
751
752       •   CPAN Testers Matrix
753
754           The CPAN Testers Matrix is a website that provides a visual
755           overview of the test results for a distribution on various
756           Perls/platforms.
757
758           <http://matrix.cpantesters.org/?dist=POE-Component-SimpleDBI>
759
760       •   CPAN Testers Dependencies
761
762           The CPAN Testers Dependencies is a website that shows a chart of
763           the test results of all dependencies for a distribution.
764
765           <http://deps.cpantesters.org/?module=POE::Component::SimpleDBI>
766
767   Email
768       You can email the author of this module at "APOCAL at cpan.org" asking
769       for help with any problems you have.
770
771   Internet Relay Chat
772       You can get live help by using IRC ( Internet Relay Chat ). If you
773       don't know what IRC is, please read this excellent guide:
774       <http://en.wikipedia.org/wiki/Internet_Relay_Chat>. Please be courteous
775       and patient when talking to us, as we might be busy or sleeping! You
776       can join those networks/channels and get help:
777
778       •   irc.perl.org
779
780           You can connect to the server at 'irc.perl.org' and join this
781           channel: #perl-help then talk to this person for help: Apocalypse.
782
783       •   irc.freenode.net
784
785           You can connect to the server at 'irc.freenode.net' and join this
786           channel: #perl then talk to this person for help: Apocal.
787
788       •   irc.efnet.org
789
790           You can connect to the server at 'irc.efnet.org' and join this
791           channel: #perl then talk to this person for help: Ap0cal.
792
793   Bugs / Feature Requests
794       Please report any bugs or feature requests by email to
795       "bug-poe-component-simpledbi at rt.cpan.org", or through the web
796       interface at
797       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-SimpleDBI>.
798       You will be automatically notified of any progress on the request by
799       the system.
800
801   Source Code
802       The code is open to the world, and available for you to hack on. Please
803       feel free to browse it and play with it, or whatever. If you want to
804       contribute patches, please send me a diff or prod me to pull from your
805       repository :)
806
807       <https://github.com/apocalypse/perl-poe-simpledbi>
808
809         git clone https://github.com/apocalypse/perl-poe-simpledbi.git
810

AUTHOR

812       Apocalypse <APOCAL@cpan.org>
813
814   CONTRIBUTORS
815       •   Apocalypse <apoc@blackhole.(none)>
816
817       •   Apocalypse <apoc@satellite.(none)>
818
819       •   Rocco Caputo <rcaputo@cpan.org>
820
822       This software is copyright (c) 2014 by Apocalypse.
823
824       This is free software; you can redistribute it and/or modify it under
825       the same terms as the Perl 5 programming language system itself.
826
827       The full text of the license can be found in the LICENSE file included
828       with this distribution.
829

DISCLAIMER OF WARRANTY

831       THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
832       APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
833       HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
834       WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
835       LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
836       PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
837       OF THE PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU
838       ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
839
840       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
841       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
842       CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
843       INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
844       ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
845       NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
846       SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO
847       OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY
848       HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
849
850
851
852perl v5.34.0                      2021-07-22    POE::Component::SimpleDBI(3pm)
Impressum