[ViewVC] Annotation 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 ($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.

    With DBD::mysql, the overhead for very simple statements ("select 0") is
    somewhere around 50% compared to an explicit
    prepare_cached/execute/fetchrow_arrayref/finish combination. With
    DBD::SQlite3, it's more like a factor of 8 for this trivial statement.

  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:

        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.

        fork_template => $AnyEvent::Fork-object
            "AnyEvent::DBI" uses "AnyEvent::Fork->new" to create the
            database slave, which in turn either "exec"'s a new process
            (similar to the old "exec_server" constructor argument) or uses
            a process forked early (see AnyEvent::Fork::Early).

            With this argument you can provide your own fork template. This
            can be useful if you create a lot of "AnyEvent::DBI" handles and
            want to save memory (And speed up startup) by not having to load
            "AnyEvent::DBI" again and again into your child processes:

               my $template = AnyEvent::Fork
                  ->new                               # create new template
                  ->require ("AnyEvent::DBI::Slave"); # preload AnyEvent::DBI::Slave module

               for (...) {
                  $dbh = new AnyEvent::DBI ...
                     fork_template => $template;

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

SEE ALSO
    AnyEvent, DBI, Coro::Mysql.

AUTHOR AND CONTACT
       Marc Lehmann <schmorp@schmorp.de> (current maintainer)
       http://home.schmorp.de/

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

Revision:	1.7
Committed:	Tue Aug 15 07:31:06 2017 UTC (6 years, 9 months ago) by root
Branch:	MAIN
CVS Tags:	rel-3_0, rel-3_01, rel-3_02, rel-3_03, rel-3_04, HEAD
Changes since 1.6:	+42 -25 lines
Log Message:	3.0
#	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	root	1.5	my ($dbh, $rows, $rv) = @_;
13
14			$#_ or die "failure: $@";
15	root	1.2
16			print "@$_\n"
17			for @$rows;
18
19			$cv->broadcast;
20			});
21
22			# asynchronously do sth. else here
23
24			$cv->wait;
25
26	root	1.1	DESCRIPTION
27			This module is an AnyEvent user, you need to make sure that you use and
28			run a supported event loop.
29
30	root	1.5	This module implements asynchronous DBI access by forking or executing
31	root	1.1	separate "DBI-Server" processes and sending them requests.
32
33			It means that you can run DBI requests in parallel to other tasks.
34
35	root	1.7	With DBD::mysql, the overhead for very simple statements ("select 0") is
36			somewhere around 50% compared to an explicit
37			prepare_cached/execute/fetchrow_arrayref/finish combination. With
38			DBD::SQlite3, it's more like a factor of 8 for this trivial statement.
39	root	1.1
40	root	1.5	ERROR HANDLING
41			This module defines a number of functions that accept a callback
42			argument. All callbacks used by this module get their AnyEvent::DBI
43			handle object passed as first argument.
44
45			If the request was successful, then there will be more arguments,
46			otherwise there will only be the $dbh argument and $@ contains an error
47			message.
48
49	root	1.7	A convenient way to check whether an error occurred is to check $#_ - if
50	root	1.5	that is true, then the function was successful, otherwise there was an
51			error.
52
53	root	1.1	METHODS
54			$dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]...
55			Returns a database handle for the given database. Each database
56			handle has an associated server process that executes statements in
57			order. If you want to run more than one statement in parallel, you
58			need to create additional database handles.
59
60			The advantage of this approach is that transactions work as state is
61			preserved.
62
63			Example:
64
65			$dbh = new AnyEvent::DBI
66			"DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "";
67
68			Additional key-value pairs can be used to adjust behaviour:
69
70			on_error => $callback->($dbh, $filename, $line, $fatal)
71			When an error occurs, then this callback will be invoked. On
72			entry, $@ is set to the error message. $filename and $line is
73			where the original request was submitted.
74
75	root	1.5	If the fatal argument is true then the database connection is
76			shut down and your database handle became invalid. In addition
77			to invoking the "on_error" callback, all of your queued request
78			callbacks are called without only the $dbh argument.
79	root	1.1
80			If omitted, then "die" will be called on any errors, fatal or
81			not.
82
83	root	1.5	on_connect => $callback->($dbh[, $success])
84			If you supply an "on_connect" callback, then this callback will
85			be invoked after the database connect attempt. If the connection
86			succeeds, $success is true, otherwise it is missing and $@
87			contains the $DBI::errstr.
88
89			Regardless of whether "on_connect" is supplied, connect errors
90			will result in "on_error" being called. However, if no
91			"on_connect" callback is supplied, then connection errors are
92			considered fatal. The client will "die" and the "on_error"
93			callback will be called with $fatal true.
94
95			When on_connect is supplied, connect error are not fatal and
96			AnyEvent::DBI will not "die". You still cannot, however, use the
97			$dbh object you received from "new" to make requests.
98
99	root	1.7	fork_template => $AnyEvent::Fork-object
100			"AnyEvent::DBI" uses "AnyEvent::Fork->new" to create the
101			database slave, which in turn either "exec"'s a new process
102			(similar to the old "exec_server" constructor argument) or uses
103			a process forked early (see AnyEvent::Fork::Early).
104
105			With this argument you can provide your own fork template. This
106			can be useful if you create a lot of "AnyEvent::DBI" handles and
107			want to save memory (And speed up startup) by not having to load
108			"AnyEvent::DBI" again and again into your child processes:
109
110			my $template = AnyEvent::Fork
111			->new # create new template
112			->require ("AnyEvent::DBI::Slave"); # preload AnyEvent::DBI::Slave module
113
114			for (...) {
115			$dbh = new AnyEvent::DBI ...
116			fork_template => $template;
117	root	1.4
118			timeout => seconds
119	root	1.5	If you supply a timeout parameter (fractional values are
120			supported), then a timer is started any time the DBI handle
121	root	1.4	expects a response from the server. This includes connection
122			setup as well as requests made to the backend. The timeout spans
123			the duration from the moment the first data is written (or
124			queued to be written) until all expected responses are returned,
125			but is postponed for "timeout" seconds each time more data is
126			returned from the server. If the timer ever goes off then a
127	root	1.5	fatal error is generated. If you have an "on_error" handler
128	root	1.4	installed, then it will be called, otherwise your program will
129			die().
130
131			When altering your databases with timeouts it is wise to use
132			transactions. If you quit due to timeout while performing
133			insert, update or schema-altering commands you can end up not
134			knowing if the action was submitted to the database,
135			complicating recovery.
136
137			Timeout errors are always fatal.
138
139			Any additional key-value pairs will be rolled into a hash reference
140	root	1.5	and passed as the final argument to the "DBI->connect (...)" call.
141	root	1.7	For example, to suppress errors on STDERR and send them instead to
142			an AnyEvent::Handle you could do:
143	root	1.4
144	root	1.5	$dbh = new AnyEvent::DBI
145			"DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "",
146			PrintError => 0,
147			on_error => sub {
148			$log_handle->push_write ("DBI Error: $@ at $_[1]:$_[2]\n");
149			};
150
151			$dbh->on_error ($cb->($dbh, $filename, $line, $fatal))
152			Sets (or clears, with "undef") the "on_error" handler.
153
154			$dbh->timeout ($seconds)
155			Sets (or clears, with "undef") the database timeout. Useful to
156			extend the timeout when you are about to make a really long query.
157	root	1.4
158	root	1.7	$dbh->attr ($attr_name[, $attr_value], $cb->($dbh, $new_value))
159			An accessor for the database handle attributes, such as
160			"AutoCommit", "RaiseError", "PrintError" and so on. If you provide
161			an $attr_value (which might be "undef"), then the given attribute
162			will be set to that value.
163
164			The callback will be passed the database handle and the attribute's
165			value if successful.
166
167			If an error occurs and the "on_error" callback returns, then only
168			$dbh will be passed and $@ contains the error message.
169
170	root	1.5	$dbh->exec ("statement", @args, $cb->($dbh, \@rows, $rv))
171	root	1.1	Executes the given SQL statement with placeholders replaced by
172			@args. The statement will be prepared and cached on the server side,
173	root	1.5	so using placeholders is extremely important.
174	root	1.1
175	root	1.4	The callback will be called with a weakened AnyEvent::DBI object as
176			the first argument and the result of "fetchall_arrayref" as (or
177			"undef" if the statement wasn't a select statement) as the second
178	root	1.5	argument.
179
180			Third argument is the return value from the "DBI->execute" method
181			call.
182
183			If an error occurs and the "on_error" callback returns, then only
184			$dbh will be passed and $@ contains the error message.
185
186	root	1.7	$dbh->stattr ($attr_name, $cb->($dbh, $value))
187			An accessor for the statement attributes of the most recently
188			executed statement, such as "NAME" or "TYPE".
189	root	1.5
190			The callback will be passed the database handle and the attribute's
191			value if successful.
192
193			If an error occurs and the "on_error" callback returns, then only
194			$dbh will be passed and $@ contains the error message.
195
196			$dbh->begin_work ($cb->($dbh[, $rc]))
197			$dbh->commit ($cb->($dbh[, $rc]))
198			$dbh->rollback ($cb->($dbh[, $rc]))
199			The begin_work, commit, and rollback methods expose the equivalent
200			transaction control method of the DBI driver. On success, $rc is
201			true.
202
203			If an error occurs and the "on_error" callback returns, then only
204			$dbh will be passed and $@ contains the error message.
205
206			$dbh->func ('string_which_yields_args_when_evaled', $func_name,
207			$cb->($dbh, $rc, $dbi_err, $dbi_errstr))
208			This gives access to database driver private methods. Because they
209			are not standard you cannot always depend on the value of $rc or
210			$dbi_err. Check the documentation for your specific driver/function
211			combination to see what it returns.
212
213			Note that the first argument will be eval'ed to produce the argument
214			list to the func() method. This must be done because the
215			serialization protocol between the AnyEvent::DBI server process and
216			your program does not support the passage of closures.
217
218			Here's an example to extend the query language in SQLite so it
219			supports an intstr() function:
220
221			$cv = AnyEvent->condvar;
222			$dbh->func (
223			q{
224			instr => 2, sub {
225			my ($string, $search) = @_;
226			return index $string, $search;
227			},
228			},
229			create_function => sub {
230			return $cv->send ($@)
231			unless $#_;
232			$cv->send (undef, @_[1,2,3]);
233			}
234			);
235
236			my ($err,$rc,$errcode,$errstr) = $cv->recv;
237
238			die $err if defined $err;
239			die "EVAL failed: $errstr"
240			if $errcode;
241	root	1.1
242	root	1.5	# otherwise, we can ignore $rc and $errcode for this particular func
243	root	1.1
244			SEE ALSO
245	root	1.5	AnyEvent, DBI, Coro::Mysql.
246	root	1.1
247	root	1.7	AUTHOR AND CONTACT
248			Marc Lehmann <schmorp@schmorp.de> (current maintainer)
249	root	1.1	http://home.schmorp.de/
250
251	root	1.4	Adam Rosenstein <adam@redcondor.com>
252			http://www.redcondor.com/
253