The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
POE-Component-SimpleDBI-1.03
River stage one • 1 direct dependent • 1 total dependent
++
/ POE::Component::SimpleDBI

NAME

POE::Component::SimpleDBI - Perl extension for asynchronous non-blocking DBI calls in POE

SYNOPSIS

        use POE;
        use POE::Component::SimpleDBI;

        # Set up the DBI
        POE::Component::SimpleDBI->new(
                ALIAS   => 'SimpleDBI',
                DSN     => 'DBI:mysql:database=foobaz;host=192.168.1.100;port=3306',
                USERNAME => 'FooBar',
                PASSWORD => 'SecretPassword',
        ) or die 'Unable to create the DBI session';

        # Create our own session to communicate with SimpleDBI
        POE::Session->create(
                inline_states => {
                        _start => sub {
                                $_[KERNEL]->post( 'SimpleDBI', 'DO',
                                        SQL => 'DELETE FROM FooTable WHERE ID = ?',
                                        PLACEHOLDERS => [ qw( 38 ) ],
                                        EVENT_S => 'deleted_handler',
                                        EVENT_E => 'error_handler',
                                );

                                $_[KERNEL]->post( 'SimpleDBI', 'SINGLE',
                                        SQL => 'Select * from FooTable',
                                        EVENT_S => 'success_handler',
                                        EVENT_E => 'error_handler',
                                );

                                $_[KERNEL]->post( 'SimpleDBI', 'MULTIPLE',
                                        SQL => 'SELECT foo, baz FROM FooTable2 WHERE id = ?',
                                        EVENT_S => 'multiple_handler',
                                        EVENT_E => 'error_handler',
                                        PLACEHOLDERS => [ qw( 53 ) ],
                                );

                                $_[KERNEL]->post( 'SimpleDBI', 'QUOTE',
                                        SQL => 'foo$*@%%sdkf"""',
                                        EVENT_S => 'quote_handler',
                                        EVENT_E => 'error_handler',
                                );

                                # 3 ways to shutdown

                                # This will let the existing queries finish, then shutdown
                                $_[KERNEL]->post( 'SimpleDBI', 'shutdown' );

                                # This will terminate when the event traverses
                                # POE's queue and arrives at SimpleDBI
                                $_[KERNEL]->post( 'SimpleDBI', 'shutdown', 'NOW' );

                                # Even QUICKER shutdown :)
                                $_[KERNEL]->call( 'SimpleDBI', 'shutdown', 'NOW' );
                        },

                        success_handler => \&success_handler,
                        deleted_handler => \&deleted_handler,
                        quote_handler   => \&quote_handler,
                        multiple_handler => \&multiple_handler,
                        error_handler => \&error_handler,
                },
        );

        sub quote_handler {
                # For QUOTE calls, we receive the scalar string of SQL quoted
                # $_[ARG0] = {
                #       SQL => The SQL You put in
                #       RESULT  => scalar quoted SQL
                #       PLACEHOLDERS => The placeholders
                #       ACTION => QUOTE
                # }
        }

        sub deleted_handler {
                # For DO calls, we receive the scalar value of rows affected
                # $_[ARG0] = {
                #       SQL => The SQL You put in
                #       RESULT  => scalar value of rows affected
                #       PLACEHOLDERS => The placeholders
                #       ACTION => DO
                # }
        }

        sub success_handler {
                # For SINGLE calls, we receive a hash ( similar to fetchrow_hash )
                # $_[ARG0] = {
                #       SQL => The SQL You put in
                #       RESULT  => hash
                #       PLACEHOLDERS => The placeholders
                #       ACTION => SINGLE
                # }
        }

        sub multiple_handler {
                # For MULTIPLE calls, we receive an array of hashes
                # $_[ARG0] = {
                #       SQL => The SQL You put in
                #       RESULT  => array of hashes
                #       PLACEHOLDERS => The placeholders
                #       ACTION => MULTIPLE
                # }
        }

        sub error_handler {
                # Errors, we receive an scalar string
                # $_[ARG0] = {
                #       SQL => The SQL You put in
                #       ERROR => ERRORSTRING
                #       PLACEHOLDERS => The placeholders
                # }
        }

ABSTRACT

        This module simplifies DBI usage in POE's multitasking world.

        This module is a breeze to use, you'll have DBI calls in your POE program
        up and running in only a few seconds of setup.

        If you want more advanced usage, check out:
                POE::Component::LaDBI

        If you want even simpler usage, check out:
                POE::Component::DBIAgent

DESCRIPTION

This module works its magic by creating a new session with POE, then spawning off a child process to do the "heavy" lifting. That way, your main POE process can continue servicing other clients.

The standard way to use this module is to do this:

        use POE;
        use POE::Component::SimpleDBI;

        POE::Component::SimpleDBI->new( ... );

        POE::Session->create( ... );

        POE::Kernel->run();

Starting SimpleDBI

To start SimpleDBI, just call it's new method:

        POE::Component::SimpleDBI->new(
                'ALIAS'         =>      'DataBase',
                'DSN'           =>      'floobarz',
                'USERNAME'      =>      'DBLogin',
                'PASSWORD'      =>      'DBPass',
        );

This method will die on error or return success.

NOTE: If the SubProcess could not connect to the DB, it will return an error, causing SimpleDBI to croak.

This constructor accepts only 4 different options.

ALIAS

This will set the alias SimpleDBI uses in the POE Kernel. This will default TO "SimpleDBI"

DSN

This is the DSN -> Database connection string

SimpleDBI expects this to contain everything you need to connect to a database via DBI, sans the username and password.

For valid DSN strings, contact your DBI manual.

USERNAME

Simply put, this is the DB username SimpleDBI will use.

PASSWORD

Simply put, this is the DB password SimpleDBI will use.

Events

There is only a few events you can trigger in SimpleDBI. They all share a common argument format, except for the shutdown event.

QUOTE
        This simply sends off a string to be quoted, and gets it back.

        Internally, it does this:

        return $dbh->quote( $SQL );

        Here's an example on how to trigger this event:

        $_[KERNEL]->post( 'SimpleDBI', 'QUOTE',
                SQL => 'foo$*@%%sdkf"""',
                EVENT_S => 'quote_handler',
                EVENT_E => 'error_handler',
        );

        The Success Event handler will get a hash in ARG0:
        {
                'SQL'           =>      Original SQL inputted
                'RESULT'        =>      Quoted SQL
        }
DO
        This query is specialized for those queries where you UPDATE/DELETE/etc.

        THIS IS NOT FOR SELECT QUERIES!

        Internally, it does this:

        $sth = $dbh->prepare_cached( $SQL );
        $rows_affected = $sth->execute( $PLACEHOLDERS );
        return $rows_affected;

        Here's an example on how to trigger this event:

        $_[KERNEL]->post( 'SimpleDBI', 'DO',
                SQL => 'DELETE FROM FooTable WHERE ID = ?',
                PLACEHOLDERS => [ qw( 38 ) ],
                EVENT_S => 'deleted_handler',
                EVENT_E => 'error_handler',
        );

        The Success Event handler will get a hash in ARG0:
        {
                'SQL'           =>      Original SQL inputted
                'RESULT'        =>      Scalar value of rows affected
                'PLACEHOLDERS'  =>      Original placeholders
        }
SINGLE
        This query is specialized for those queries where you will get exactly 1 result back.

        NOTE: This subroutine will automatically append ' LIMIT 1' to all queries passed in.

        Internally, it does this:

        $sth = $dbh->prepare_cached( $SQL );
        $sth->bind_columns( %result );
        $sth->execute( $PLACEHOLDERS );
        $sth->fetch();
        return %result;

        Here's an example on how to trigger this event:

        $_[KERNEL]->post( 'SimpleDBI', 'SINGLE',
                SQL => 'Select * from FooTable',
                EVENT_S => 'success_handler',
                EVENT_E => 'error_handler',
        );

        The Success Event handler will get a hash in ARG0:
        {
                'SQL'           =>      Original SQL inputted
                'RESULT'        =>      Hash of rows - similar to fetchrow_hashref
                'PLACEHOLDERS'  =>      Original placeholders
        }
MULTIPLE
        This query is specialized for those queries where you will get more than 1 result back.

        Internally, it does this:

        $sth = $dbh->prepare_cached( $SQL );
        $sth->bind_columns( %row );
        $sth->execute( $PLACEHOLDERS );
        while ( $sth->fetch() ) {
                push( @results, %row );
        }
        return @results;

        Here's an example on how to trigger this event:

        $_[KERNEL]->post( 'SimpleDBI', 'MULTIPLE',
                SQL => 'SELECT foo, baz FROM FooTable2 WHERE id = ?',
                EVENT_S => 'multiple_handler',
                EVENT_E => 'error_handler',
                PLACEHOLDERS => [ qw( 53 ) ],
        );

        The Success Event handler will get a hash in ARG0:
        {
                'SQL'           =>      Original SQL inputted
                'RESULT'        =>      Array of hash of rows ( array of fetchrow_hashref's )
                'PLACEHOLDERS'  =>      Original placeholders
        }
Shutdown
        $_[KERNEL]->post( 'SimpleDBI', 'shutdown' );

        This will signal SimpleDBI to start the shutdown procedure.

        NOTE: This will let all outstanding queries run!
        SimpleDBI will kill it's session when all the queries have been processed.

        you can also specify an argument:

        $_[KERNEL]->post( 'SimpleDBI', 'shutdown', 'NOW' );

        This will signal SimpleDBI to shutdown.

        NOTE: This will NOT let the outstanding queries finish!
        Any queries running will be lost!

        Due to the way POE's queue works, this shutdown event will take some time to propagate POE's queue.
        If you REALLY want to shut down immediately, do this:

        $_[KERNEL]->call( 'SimpleDBI', 'shutdown', 'NOW' );

Arguments

They are passed in via the $_[KERNEL]->post( ... );

NOTE: Capitalization is very important!

SQL

This is the actual SQL line you want SimpleDBI to execute. You can put in placeholders, this module supports them.

PLACEHOLDERS

This is an array of placeholders.

You can skip this if your query does not utilize it.

EVENT_S

This is the success event, triggered whenever a query finished successfully.

It will get a hash in ARG0, consult the specific queries on what you will get.

EVENT_E

This is the error event, triggered whenever a query gets an error.

It will get a plain string in ARG0, signifying the error.

SimpleDBI Notes

This module is very picky about capitalization!

All of the options are uppercase, to avoid confusion.

You can enable debugging mode by doing this:

        sub POE::Component::SimpleDBI::DEBUG () { 1 }
        use POE::Component::SimpleDBI;

Also, this module will try to keep the SubProcess alive. if it dies, it will open it again for a max of 5 retries.

You can override this behavior by doing this:

        sub POE::Component::SimpleDBI::MAX_RETRIES () { 10 }
        use POE::Component::SimpleDBI;

EXPORT

Nothing.

SEE ALSO

DBI

POE

POE::Wheel::Run

POE::Component::DBIAgent

POE::Component::LaDBI

AUTHOR

Apocalypse <apocal@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2003 by Apocalypse

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.