Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DBI(3)		      User Contributed Perl Documentation		DBI(3)

       AnyEvent::DBI - asynchronous DBI	access

	  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;


	  # asynchronously do sth. else	here


       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.

       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

       A convinient way	to check whether an error occured is to	check $#_ - if
       that is true, then the function was successful, otherwise there was an

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


	      $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

	   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 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, 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

	   Third argument is the return	value from the "DBI->execute" method

	   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

	   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 (
		     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

       AnyEvent, DBI, Coro::Mysql.

	  Marc Lehmann <>

	  Adam Rosenstein <>

perl v5.32.0			  2013-04-02				DBI(3)


Want to link to this manual page? Use this URL:

home | help