/ 
DBIx-Poggy-0.08
River stage zero No dependents
/ DBIx::Poggy

NAME

DBIx::Poggy - async Pg with AnyEvent and Promises

SYNOPSIS

use strict;
use warnings;

use DBIx::Poggy;
my $pool = DBIx::Poggy->new( pool_size => 5 );
$pool->connect('dbi:Pg:db=test', 'root', 'password');

use AnyEvent;
my $cv = AnyEvent->condvar;

my $res;
$pool->take->selectrow_arrayref(
    'SELECT * FROM users WHERE name = ?', {}, 'ruz'
)
->then(sub {
    my $user = $res->{user} = shift;

    return $pool->take->selectall_arrayref(
        'SELECT * FROM friends WHERE user_id = ?', undef, $user->{id}
    );
})
->then(sub {
    my $friends = $res->{friends} = shift;
    ...
})
->catch(sub {
    my $error = shift;
    die $error;
})
->finally(sub {
    $cv->send( $res );
});

$cv->recv;

DESCRIPTION

"Async" postgres as much as DBD::Pg allows with Promises instead of callbacks.

You get DBI interface you used to that returns promises, connections pool, queries queuing and support of transactions.

Why pool?

DBD::Pg is not async, it's non blocking. Every connection can execute only one query at a moment, so to execute several queries in parallel you need several connections. What you get is you can do something in Perl side while postgres crunches data for you.

Queue

Usually if you attempt to run two queries on the same connection then DBI throws an error about active query. Poggy takes care of that by queuing up queries you run on one connection. Handy for transactions and pool doesn't grow too much.

What is async here then?

Only a queries on multiple connections, so if you need to execute many parallel queries then you need many connections. pg_bouncer and haproxy are your friends.

Pool management

In auto mode (default) you just "loose" reference to database handle and it gets released back into the pool after all queries are done:

{
    my $cv = AnyEvent->condvar;
    $pool->take->do(...)->finally($cv);
    $cv->recv;
}
# released

Or: { my $cv = AnyEvent->condvar; my $dbh = $pool->take; $dbh->do(...) ->then(sub { $dbh->do(...) }) ->then(sub { ... }) ->finally($cv); $cv->recv; } # $dbh goes out of scope and all queries are done (cuz of condvar) # released

METHODS

new

Named arguments:

pool_size

number of connections to create, creates one more in case all are busy

Returns a new pool object.

connect

Takes the same arguments as "connect" in DBI, opens "pool_size" connections. Saves connection settings for reuse when pool is exhausted.

take

Gives one connection from the pool. Takes arguments:

auto

Connection will be released to the pool once dbh goes out of scope (gets "DESTROYED"). True by default.

Returns DBIx::Poggy::DBI handle. When "auto" is turned off then in list context returns also guard object that will "release" handle to the pool on destruction.

release

Takes a handle as argument and puts it back into the pool. At the moment, no protection against double putting or active queries on the handle.

AUTHOR

Ruslan U. Zakirov <Ruslan.Zakirov@gmail.com>

LICENSE

Under the same terms as perl itself.