[ViewVC] Annotation of: cvs/cvsroot/AnyEvent-DBI/README

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 <schmorp@schmorp.de>
       http://home.schmorp.de/

       Adam Rosenstein <adam@redcondor.com>
       http://www.redcondor.com/

Revision:	1.4
Committed:	Tue Jun 2 16:16:03 2009 UTC (17 years, 3 months ago) by root
Branch:	MAIN
Changes since 1.3:	+76 -9 lines
Log Message:	big patch by adam
#	User	Rev	Content
1	root	1.1	NAME
2			AnyEvent::DBI - asynchronous DBI access
3
4			SYNOPSIS
5			use AnyEvent::DBI;
6
7	root	1.2	my $cv = AnyEvent->condvar;
8
9			my $dbh = new AnyEvent::DBI "DBI:SQLite:dbname=test.db", "", "";
10
11			$dbh->exec ("select * from test where num=?", 10, sub {
12			my ($rows, $rv) = @_;
13
14			print "@$_\n"
15			for @$rows;
16
17			$cv->broadcast;
18			});
19
20			# asynchronously do sth. else here
21
22			$cv->wait;
23
24	root	1.1	DESCRIPTION
25			This module is an AnyEvent user, you need to make sure that you use and
26			run a supported event loop.
27
28	root	1.4	This module implements asynchronous DBI access my forking or executing
29	root	1.1	separate "DBI-Server" processes and sending them requests.
30
31			It means that you can run DBI requests in parallel to other tasks.
32
33			The overhead for very simple statements ("select 0") is somewhere around
34	root	1.2	120% to 200% (dual/single core CPU) compared to an explicit
35	root	1.1	prepare_cached/execute/fetchrow_arrayref/finish combination.
36
37			METHODS
38			$dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]...
39			Returns a database handle for the given database. Each database
40			handle has an associated server process that executes statements in
41			order. If you want to run more than one statement in parallel, you
42			need to create additional database handles.
43
44			The advantage of this approach is that transactions work as state is
45			preserved.
46
47			Example:
48
49			$dbh = new AnyEvent::DBI
50			"DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "";
51
52			Additional key-value pairs can be used to adjust behaviour:
53
54			on_error => $callback->($dbh, $filename, $line, $fatal)
55			When an error occurs, then this callback will be invoked. On
56			entry, $@ is set to the error message. $filename and $line is
57			where the original request was submitted.
58
59	root	1.4	If the fatal argument is true then the database connection shuts
60			down and your database handle becomes invalid. All of your
61			request callbacks are called without any arguments.
62	root	1.1
63			If omitted, then "die" will be called on any errors, fatal or
64			not.
65
66	root	1.4	The $dbh argument is always a weak reference to the
67			AnyEvent::DBI object.
68
69			on_connect => $callback->($dbh)
70			If you supply an on_connect callback, then this callback will be
71			invoked after the database connection is attempted. If the
72			connection succeeds, $dbh contains a weak reference to the
73			AnyEvent::DBI object. If the connection fails for any reason, no
74			arguments are passed to the callback and $@ contains
75			$DBI::errstr.
76
77			Regardless of whether on_connect is supplied, connect errors
78			will result in on_error being called. However, if no on_connect
79			callback is supplied, then connection errors are considered
80			fatal. The client will die() and the on_error callback will be
81			called with $fatal true. When on_connect is supplied, connect
82			error are not fatal and AnyEvent::DBI will not die(). You still
83			cannot, however, use the $dbh object you recived from new() to
84			make requests.
85
86			timeout => seconds
87			If you supply a timeout parameter (floating point number of
88			seconds), then a timer is started any time the DBI handle
89			expects a response from the server. This includes connection
90			setup as well as requests made to the backend. The timeout spans
91			the duration from the moment the first data is written (or
92			queued to be written) until all expected responses are returned,
93			but is postponed for "timeout" seconds each time more data is
94			returned from the server. If the timer ever goes off then a
95			fatal error is generated. If you have an on_error handler
96			installed, then it will be called, otherwise your program will
97			die().
98
99			When altering your databases with timeouts it is wise to use
100			transactions. If you quit due to timeout while performing
101			insert, update or schema-altering commands you can end up not
102			knowing if the action was submitted to the database,
103			complicating recovery.
104
105			Timeout errors are always fatal.
106
107			Any additional key-value pairs will be rolled into a hash reference
108			and passed as the final argument to the DBI->connect(...) call. For
109			example, to supress errors on STDERR and send them instead to an
110			AnyEvent::Handle you could do:
111
112			$dbh = new AnyEvent::DBI
113			"DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "",
114			PrintError => 0,
115			on_error => sub { $log_handle->push_write("DBI Error: $@ at $_[1]:$_[2]\n"); }
116
117			$dbh->on_error ( $cb->($dbh, $filename, $line, $fatal) );
118			Sets (or clears) the on_error handler.
119
120			$dbh->on_connect ( $cb->($dbh) ) ;
121			Sets (or clears) the on_connect handler.
122
123			$dbh->timeout ( $seconds ) ;
124			Sets (or clears) the database timeout. Useful to extend the timeout
125			when you are about to make a really long query.
126
127			$dbh->exec ("statement", @args, $cb->($dbh, \@rows, \%metadata ))
128	root	1.1	Executes the given SQL statement with placeholders replaced by
129			@args. The statement will be prepared and cached on the server side,
130			so using placeholders is compulsory.
131
132	root	1.4	The callback will be called with a weakened AnyEvent::DBI object as
133			the first argument and the result of "fetchall_arrayref" as (or
134			"undef" if the statement wasn't a select statement) as the second
135			argument. Third argument is a hash reference holding metadata about
136			the request. Currently, the only key defined is "$metadata-"{rv}>
137			holding the return value of "execute". Additional metadata might be
138			added.
139	root	1.1
140			If an error occurs and the "on_error" callback returns, then no
141			arguments will be passed and $@ contains the error message.
142
143			SEE ALSO
144			AnyEvent, DBI.
145
146			AUTHOR
147			Marc Lehmann <schmorp@schmorp.de>
148			http://home.schmorp.de/
149
150	root	1.4	Adam Rosenstein <adam@redcondor.com>
151			http://www.redcondor.com/
152