[ViewVC] Contents of: cvs/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 (14 years, 11 months ago) by root
Branch:	MAIN
Changes since 1.3:	+76 -9 lines
Log Message:	big patch by adam
#	Content
1	NAME
2	AnyEvent::DBI - asynchronous DBI access
3
4	SYNOPSIS
5	use AnyEvent::DBI;
6
7	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	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	This module implements asynchronous DBI access my forking or executing
29	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	120% to 200% (dual/single core CPU) compared to an explicit
35	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	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
63	If omitted, then "die" will be called on any errors, fatal or
64	not.
65
66	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	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	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
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	Adam Rosenstein <adam@redcondor.com>
151	http://www.redcondor.com/
152