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

  *******************************************************************
  ***                                                             ***
  *** NOTE: This is a very early release that may contain lots of ***
  *** bugs. The API is not stable and may change between releases ***
  ***                                                             ***
  *******************************************************************

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).

The following options are accepted:

on_connect => sub { ... }

The given callback is invoked after the connection has been successfully established.

on_connect_error => sub { ... }

This callback is invoked if a fatal error happens when establishing the connection to the database server.

on_empty_queue => sub { ... }

This callback is called every time the query queue becomes empty.

on_notify => sub { ... }

This callback is called when a notification is received.

on_error => sub { ... }

This callback is called when some error happens.

timeout => $seconds

Sets the default timeout for network activity. When nothing happens on the network for the given seconds while processing some query, the connection is marked as dead.

$w = $adb->push_query(%opts)

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

Returns a query watcher object. Destroying the watcher (usually when it gets unreferenced) cancels the query.

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 statement 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.

$w = $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.

$w = $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.

$w = $adb->unshift_query(%opts)

$w = $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->abort_all

Marks the connection as dead and aborts any queued queries calling the on_error callbacks.

$adb->queue_size

Returns the number of queries queued for execution.

$adb->finish

Closes the connection to the database and frees the associated resources.

SEE ALSO

Pg::PQ, AnyEvent, AnyEvent::Pg::Pool.

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-2013 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.