DBIAgent::Helper(3pm)

💖 DBIAgent::Helper — the manual page, but make it cute 💖

okay bestie, so this is DBIAgent::Helper(3pm) from the User Contributed Perl Documentation, and it is literally the little helper that keeps POE::Component::DBIAgent fed. no cap. let's get into it 🫶

---

✨ NAME ✨

POE::Component::DBIAgent::Helper — the DBI Query Helper for DBIAgent. it's giving "supporting character who's actually carrying the whole plot" 💅

---

✨ SYNOPSYS ✨

yes it's spelled like that, leave her alone, she's iconic 💜

use Socket qw/:crlf/;
use POE qw/Filter::Line Wheel::Run Component::DBIAgent::Helper/;

sub _start {
    my $helper = POE::Wheel::Run ->new(
            Program     => sub {
                POE::Component::DBIAgent::Helper->run($self->{dsn},
                                                      $self->{queries}
                                                     );
            },
            StdoutEvent => 'db_reply',
            StderrEvent => 'remote_stderr',
            ErrorEvent  => 'error',
            StdinFilter => POE::Filter::Line->new(),
            StdoutFilter => POE::Filter::Line->new( Literal => CRLF),
            StderrFilter => POE::Filter::Line->new(),
           )
     or carp "Can't create new DBIAgent::Helper: $!\n";

}

sub query {
     my ($self, $query, $package, $state, @rest) = @_;

     $self->{helper}->put(join '|', $query, $package, $state, @rest);
}

sub db_reply {
   my ($kernel, $self, $heap, $input) = @_[KERNEL, OBJECT, HEAP, ARG0];

   # $input is either the string 'EOF' or a Storable object.

}

like. look at that. StdoutFilter => POE::Filter::Line->new( Literal => CRLF) is doing SO much heavy lifting and nobody ever says thank you 😭

---

✨ DESCRIPTION ✨

so here's the tea, bestie 🍓

this is the helper routine for DBIAgent. she accepts queries on STDIN, and she returns the results on STDOUT. queries come back on a row-by-row basis, followed by a row that is literally just the string 'EOF'.

each row is the return value of $sth->fetch, which is an arrayref. that row then gets passed to Storable for transport, and printed to STDOUT. HOWEVER — and this part is the plot twist, pay attention — Storable uses newlines ("\n") in its serialized strings. so the Helper is designed to use the "network newline" pair CR LF as the line terminator for STDOUT. it's giving protocol matchmaking fr fr 🎀

when fetch() returns undef, one final row gets returned to the calling state: the string 'EOF'. and sessions should test for this value FIRST when they're being invoked with input from a query. like, first first. before anything else. do not skip this step or you will be in your flop era 💀

🌸 Initialization 🌸

the Helper has one public subroutine, called run(), and you invoke it with two parameters:

• The DSN — an arrayref of parameters to pass to DBI->connect (usually a dsn, username, and password). that's the trio, periodt.
• The Queries. — a hashref of the form Query_Name => "$SQL". see POE::Component::DBIAgent for details, iykyk 👑

---

✨ BUGS ✨

okay so I have NO idea what to do about handling signals intelligently. none. zero. n/a. 🙈

specifically: under some circumstances, Oracle will refuse to acknowledge SIGTERM (presumably since its libraries are non-reentrant), so sometimes SIGKILL is required to terminate a Helper process. so like... yeah. that's the vibe. dramatic but true 💀

---

✨ AUTHOR ✨

this module has been fine-tuned and packaged by Rob Bloodgood <robb@empire2.com>. but most of the code came directly from Fletch <fletch@phydeaux.org>, either directly (Po:Co:DBIAgent:Queue) or via his ideas. Thank you, Fletch! 🫶✨

however, I own all of the bugs. every single one. they're mine. no notes. 💅

this module is free software; you may redistribute it and/or modify it under the same terms as Perl itself. iconic behaviour honestly 👑

---

🌈 cute little sign-off time: this page is DBIAgent::Helper(3pm) as shipped with perl v5.32.0, dated 2021-01-08. slay, go run your queries, and remember to check for that 'EOF' first bestie 💖🦋🌸