NAME AnyEvent::DBI - asynchronous DBI access SYNOPSIS use AnyEvent::DBI; my $cv = AnyEvent->condvar; my $dbh = new AnyEvent::DBI "DBI:SQLite:dbname=test.db", "", ""; $dbh->exec ("select * from test where num=?", 10, sub { my ($rows, $rv) = @_; print "@$_\n" for @$rows; $cv->broadcast; }); # asynchronously do sth. else here $cv->wait; DESCRIPTION This module is an AnyEvent user, you need to make sure that you use and run a supported event loop. This module implements asynchronous DBI access my forking or executing separate "DBI-Server" processes and sending them requests. It means that you can run DBI requests in parallel to other tasks. The overhead for very simple statements ("select 0") is somewhere around 120% to 200% (dual/single core CPU) compared to an explicit prepare_cached/execute/fetchrow_arrayref/finish combination. METHODS $dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]... Returns a database handle for the given database. Each database handle has an associated server process that executes statements in order. If you want to run more than one statement in parallel, you need to create additional database handles. The advantage of this approach is that transactions work as state is preserved. Example: $dbh = new AnyEvent::DBI "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", ""; Additional key-value pairs can be used to adjust behaviour: on_error => $callback->($dbh, $filename, $line, $fatal) When an error occurs, then this callback will be invoked. On entry, $@ is set to the error message. $filename and $line is where the original request was submitted. If the fatal argument is true then the database connection shuts down and your database handle becomes invalid. All of your request callbacks are called without any arguments. If omitted, then "die" will be called on any errors, fatal or not. The $dbh argument is always a weak reference to the AnyEvent::DBI object. on_connect => $callback->($dbh) If you supply an on_connect callback, then this callback will be invoked after the database connection is attempted. If the connection succeeds, $dbh contains a weak reference to the AnyEvent::DBI object. If the connection fails for any reason, no arguments are passed to the callback and $@ contains $DBI::errstr. Regardless of whether on_connect is supplied, connect errors will result in on_error being called. However, if no on_connect callback is supplied, then connection errors are considered fatal. The client will die() and the on_error callback will be called with $fatal true. When on_connect is supplied, connect error are not fatal and AnyEvent::DBI will not die(). You still cannot, however, use the $dbh object you recived from new() to make requests. timeout => seconds If you supply a timeout parameter (floating point number of seconds), then a timer is started any time the DBI handle expects a response from the server. This includes connection setup as well as requests made to the backend. The timeout spans the duration from the moment the first data is written (or queued to be written) until all expected responses are returned, but is postponed for "timeout" seconds each time more data is returned from the server. If the timer ever goes off then a fatal error is generated. If you have an on_error handler installed, then it will be called, otherwise your program will die(). When altering your databases with timeouts it is wise to use transactions. If you quit due to timeout while performing insert, update or schema-altering commands you can end up not knowing if the action was submitted to the database, complicating recovery. Timeout errors are always fatal. Any additional key-value pairs will be rolled into a hash reference and passed as the final argument to the DBI->connect(...) call. For example, to supress errors on STDERR and send them instead to an AnyEvent::Handle you could do: $dbh = new AnyEvent::DBI "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "", PrintError => 0, on_error => sub { $log_handle->push_write("DBI Error: $@ at $_[1]:$_[2]\n"); } $dbh->on_error ( $cb->($dbh, $filename, $line, $fatal) ); Sets (or clears) the on_error handler. $dbh->on_connect ( $cb->($dbh) ) ; Sets (or clears) the on_connect handler. $dbh->timeout ( $seconds ) ; Sets (or clears) the database timeout. Useful to extend the timeout when you are about to make a really long query. $dbh->exec ("statement", @args, $cb->($dbh, \@rows, \%metadata )) Executes the given SQL statement with placeholders replaced by @args. The statement will be prepared and cached on the server side, so using placeholders is compulsory. The callback will be called with a weakened AnyEvent::DBI object as the first argument and the result of "fetchall_arrayref" as (or "undef" if the statement wasn't a select statement) as the second argument. Third argument is a hash reference holding metadata about the request. Currently, the only key defined is "$metadata-"{rv}> holding the return value of "execute". Additional metadata might be added. If an error occurs and the "on_error" callback returns, then no arguments will be passed and $@ contains the error message. SEE ALSO AnyEvent, DBI. AUTHOR Marc Lehmann http://home.schmorp.de/ Adam Rosenstein http://www.redcondor.com/