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 occurred 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:

   $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->attr ($attr_name[, $attr_value], $cb->($dbh, $new_value))

An accessor for the database 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->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->stattr ($attr_name, $cb->($dbh, $value))

An accessor for the statement attributes of the most recently executed statement, such as "NAME" or "TYPE".

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