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 ($dbh, $rows, $rv) = @_;
$#_ or die "failure: $@";
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 by 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 100% to 120% (dual/single core CPU) compared to an explicit
prepare_cached/execute/fetchrow_arrayref/finish combination.
ERROR HANDLING¶
This module defines a number of functions that accept a callback argument. All
callbacks used by this module get their AnyEvent::DBI handle object passed as
first argument.
If the request was successful, then there will be more arguments, otherwise
there will only be the $dbh argument and $@ contains an error message.
A convenient way to check whether an error occured is to check $#_ - if that is
true, then the function was successful, otherwise there was an error.
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 is shut down and
your database handle became invalid. In addition to invoking the
"on_error" callback, all of your queued request callbacks are
called without only the $dbh argument.
If omitted, then "die" will be called on any errors, fatal or
not.
- on_connect => $callback->($dbh[, $success])
- If you supply an "on_connect" callback, then this callback will
be invoked after the database connect attempt. If the connection succeeds,
$success is true, otherwise it is missing and $@ contains the
$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 received from "new" to make requests.
- exec_server => 1
- If you supply an "exec_server" argument, then the DBI server
process will fork and exec another perl interpreter (using $^X) with just
the AnyEvent::DBI proxy running. This will provide the cleanest possible
proxy for your database server.
If you do not supply the "exec_server" argument (or supply it with
a false value) then the traditional method of starting the server by
forking the current process is used. The forked interpreter will try to
clean itself up by calling POSIX::close on all file descriptors except
STDIN, STDOUT, and STDERR (and the socket it uses to communicate with the
cilent, of course).
- timeout => seconds
- If you supply a timeout parameter (fractional values are supported), 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 suppress 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, with "undef") the "on_error"
handler.
- $dbh->timeout ($seconds)
- Sets (or clears, with "undef") 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,
$rv))
- 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 extremely important.
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 the return value from the "DBI->execute"
method call.
If an error occurs and the "on_error" callback returns, then only
$dbh will be passed and $@ contains the error message.
- $dbh->attr ($attr_name[, $attr_value], $cb->($dbh, $new_value))
- An accessor for the handle attributes, such as "AutoCommit",
"RaiseError", "PrintError" and so on. If you provide
an $attr_value (which might be "undef"), then the given
attribute will be set to that value.
The callback will be passed the database handle and the attribute's value if
successful.
If an error occurs and the "on_error" callback returns, then only
$dbh will be passed and $@ contains the error message.
- $dbh->begin_work ($cb->($dbh[, $rc]))
- $dbh->commit ($cb->($dbh[, $rc]))
- $dbh->rollback ($cb->($dbh[, $rc]))
- The begin_work, commit, and rollback methods expose the equivalent
transaction control method of the DBI driver. On success, $rc is true.
If an error occurs and the "on_error" callback returns, then only
$dbh will be passed and $@ contains the error message.
- $dbh->func ('string_which_yields_args_when_evaled', $func_name,
$cb->($dbh, $rc, $dbi_err, $dbi_errstr))
- This gives access to database driver private methods. Because they are not
standard you cannot always depend on the value of $rc or $dbi_err. Check
the documentation for your specific driver/function combination to see
what it returns.
Note that the first argument will be eval'ed to produce the argument list to
the func() method. This must be done because the serialization
protocol between the AnyEvent::DBI server process and your program does
not support the passage of closures.
Here's an example to extend the query language in SQLite so it supports an
intstr() function:
$cv = AnyEvent->condvar;
$dbh->func (
q{
instr => 2, sub {
my ($string, $search) = @_;
return index $string, $search;
},
},
create_function => sub {
return $cv->send ($@)
unless $#_;
$cv->send (undef, @_[1,2,3]);
}
);
my ($err,$rc,$errcode,$errstr) = $cv->recv;
die $err if defined $err;
die "EVAL failed: $errstr"
if $errcode;
# otherwise, we can ignore $rc and $errcode for this particular func
SEE ALSO¶
AnyEvent, DBI, Coro::Mysql.
AUTHOR¶
Marc Lehmann <schmorp@schmorp.de>
http://home.schmorp.de/
Adam Rosenstein <adam@redcondor.com>
http://www.redcondor.com/