NAME

AnyEvent::Pg - Query a PostgreSQL database asynchronously

SYNOPSIS

  use AnyEvent::Pg;
  my $db = AnyEvent::Pg->new("dbname=foo",
                             on_connect => sub { ... });

  $db->push_query(query => 'insert into foo (id, name) values(7, \'seven\')',
                  on_result => sub { ... },
                  on_error => sub { ... } );

  # Note that $1, $2, etc. are Pg placeholders, nothing to do with
  # Perl regexp captures!

  $db->push_query(query => ['insert into foo (id, name) values($1, $2)', 7, 'seven']
                  on_result => sub { ... }, ...);

  $db->push_prepare(name => 'insert_into_foo',
                    query => 'insert into foo (id, name) values($1, $2)',
                    on_result => sub { ... }, ...);

  $db->push_query_prepared(name => 'insert_into_foo',
                           args => [7, 'seven'],
                           on_result => sub { ... }, ...);

DESCRIPTION

This library allows to query PostgreSQL databases asynchronously. It is a thin layer on top of Pg::PQ that integrates it inside the AnyEvent framework.

API

The following methods are available from the AnyEvent::Pg class:

$adb = AnyEvent::Pg->new($conninfo, %opts)

Creates and starts the connection to the database. $conninfo contains the parameters defining how to connect to the database (see libpq PQconnectdbParams and PQconnectdb documentation for the details: http://www.postgresql.org/docs/9.0/interactive/libpq-connect.html).

$adb->push_query(%opts)

Pushes a query into the object queue that will eventually be dispatched to the database.

The accepted options are:

query => $sql_query

The SQL query to be passed to the database

query => [$sql_query, @args]

A SQL query with placeholders ($1, $2, $3, etc.) and the arguments.

args => \@args

An alternative way to pass the arguments to a SQL query with placeholders.

on_error => sub { ... }

The given callback will be called when the query processing fails for any reason.

on_result => sub { ... }

The given callback will be called for every result returned for the given query.

You should expect one result object for every SQL statment on the query.

The callback will receive as its arguments the AnyEvent::Pg and the Pg::PQ::Result object.

on_done => sub { ... }

This callback will be run after the last result from the query is processed. The AnyEvent::Pg object is passed as an argument.

$adb->push_prepare(%opts)

Queues a query prepare operation for execution.

The accepted options are:

name => $name

Name of the prepared query.

query => $sql

SQL code for the prepared query.

on_error => sub { ... }

on_result => sub { ... }

on_done => sub { ... }

These callbacks perform in the same fashion as on the push_query method.

$adb->push_query_prepared(%opts)

Queues a prepared query for execution.

The accepted options are:

name => $name

Name of the prepared query.

args => \@args

Arguments for the query.

on_result => sub { ... }

on_done => sub { ... }

on_error => sub { ... }

These callbacks work as on the push_query method.

$adb->unshift_query(%opts)

$adb->unshift_query_prepared(%opts)

These method work in the same way as its push counterparts, but instead of pushing the query at the end of the queue they push (unshift) it at the beginning to be executed just after the current one is done.

This methods can be used as a way to run transactions composed of several queries.

$adb->fail

Aborts any queued queries calling the on_error callbacks.

$adb->destroy

SEE ALSO

Pg::PQ, AnyEvent.

AnyEvent::DBD::Pg provides non-blocking access to a PostgreSQL through DBD::Pg, but note that DBD::Pg does not provides a complete asynchronous interface (for instance, establishing new connections is always a blocking operation).

Protocol::PostgreSQL: pure Perl implementation of the PostgreSQL client-server protocol that can be used in non-blocking mode.

BUGS AND SUPPORT

This is a very early release that may contain lots of bugs.

Send bug reports by email or using the CPAN bug tracker at https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=AnyEvent-Pg.

Commercial support

This module was implemented during the development of QVD (http://theqvd.com) the Linux VDI platform.

Commercial support, professional services and custom software development services around this module are available from QindelGroup (http://qindel.com). Send us an email with a rough description of your requirements and we will get back to you ASAP.

AUTHOR

Salvador Fandiño, <sfandino@yahoo.com>

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Qindel Formación y Servicios S.L.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.