ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-DBI/README
(Generate patch)

Comparing AnyEvent-DBI/README (file contents):
Revision 1.4 by root, Tue Jun 2 16:16:03 2009 UTC vs.
Revision 1.7 by root, Tue Aug 15 07:31:06 2017 UTC

… …
7 my $cv = AnyEvent->condvar; 7 my $cv = AnyEvent->condvar;
8 8
9 my $dbh = new AnyEvent::DBI "DBI:SQLite:dbname=test.db", "", ""; 9 my $dbh = new AnyEvent::DBI "DBI:SQLite:dbname=test.db", "", "";
10 10
11 $dbh->exec ("select * from test where num=?", 10, sub { 11 $dbh->exec ("select * from test where num=?", 10, sub {
12 my ($rows, $rv) = @_; 12 my ($dbh, $rows, $rv) = @_;
13
14 $#_ or die "failure: $@";
13 15
14 print "@$_\n" 16 print "@$_\n"
15 for @$rows; 17 for @$rows;
16 18
17 $cv->broadcast; 19 $cv->broadcast;
… …
23 25
24DESCRIPTION 26DESCRIPTION
25 This module is an AnyEvent user, you need to make sure that you use and 27 This module is an AnyEvent user, you need to make sure that you use and
26 run a supported event loop. 28 run a supported event loop.
27 29
28 This module implements asynchronous DBI access my forking or executing 30 This module implements asynchronous DBI access by forking or executing
29 separate "DBI-Server" processes and sending them requests. 31 separate "DBI-Server" processes and sending them requests.
30 32
31 It means that you can run DBI requests in parallel to other tasks. 33 It means that you can run DBI requests in parallel to other tasks.
32 34
33 The overhead for very simple statements ("select 0") is somewhere around 35 With DBD::mysql, the overhead for very simple statements ("select 0") is
34 120% to 200% (dual/single core CPU) compared to an explicit 36 somewhere around 50% compared to an explicit
35 prepare_cached/execute/fetchrow_arrayref/finish combination. 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
40 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 A convenient way to check whether an error occurred is to check $#_ - if
50 that is true, then the function was successful, otherwise there was an
51 error.
36 52
37 METHODS 53 METHODS
38 $dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]... 54 $dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]...
39 Returns a database handle for the given database. Each database 55 Returns a database handle for the given database. Each database
40 handle has an associated server process that executes statements in 56 handle has an associated server process that executes statements in
… …
54 on_error => $callback->($dbh, $filename, $line, $fatal) 70 on_error => $callback->($dbh, $filename, $line, $fatal)
55 When an error occurs, then this callback will be invoked. On 71 When an error occurs, then this callback will be invoked. On
56 entry, $@ is set to the error message. $filename and $line is 72 entry, $@ is set to the error message. $filename and $line is
57 where the original request was submitted. 73 where the original request was submitted.
58 74
59 If the fatal argument is true then the database connection shuts 75 If the fatal argument is true then the database connection is
60 down and your database handle becomes invalid. All of your 76 shut down and your database handle became invalid. In addition
77 to invoking the "on_error" callback, all of your queued request
61 request callbacks are called without any arguments. 78 callbacks are called without only the $dbh argument.
62 79
63 If omitted, then "die" will be called on any errors, fatal or 80 If omitted, then "die" will be called on any errors, fatal or
64 not. 81 not.
65 82
66 The $dbh argument is always a weak reference to the
67 AnyEvent::DBI object.
68
69 on_connect => $callback->($dbh) 83 on_connect => $callback->($dbh[, $success])
70 If you supply an on_connect callback, then this callback will be 84 If you supply an "on_connect" callback, then this callback will
71 invoked after the database connection is attempted. If the 85 be invoked after the database connect attempt. If the connection
72 connection succeeds, $dbh contains a weak reference to the 86 succeeds, $success is true, otherwise it is missing and $@
73 AnyEvent::DBI object. If the connection fails for any reason, no
74 arguments are passed to the callback and $@ contains
75 $DBI::errstr. 87 contains the $DBI::errstr.
76 88
77 Regardless of whether on_connect is supplied, connect errors 89 Regardless of whether "on_connect" is supplied, connect errors
78 will result in on_error being called. However, if no on_connect 90 will result in "on_error" being called. However, if no
79 callback is supplied, then connection errors are considered 91 "on_connect" callback is supplied, then connection errors are
80 fatal. The client will die() and the on_error callback will be 92 considered fatal. The client will "die" and the "on_error"
81 called with $fatal true. When on_connect is supplied, connect 93 callback will be called with $fatal true.
82 error are not fatal and AnyEvent::DBI will not die(). You still 94
83 cannot, however, use the $dbh object you recived from new() to 95 When on_connect is supplied, connect error are not fatal and
84 make requests. 96 AnyEvent::DBI will not "die". You still cannot, however, use the
97 $dbh object you received from "new" to make requests.
98
99 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;
85 117
86 timeout => seconds 118 timeout => seconds
87 If you supply a timeout parameter (floating point number of 119 If you supply a timeout parameter (fractional values are
88 seconds), then a timer is started any time the DBI handle 120 supported), then a timer is started any time the DBI handle
89 expects a response from the server. This includes connection 121 expects a response from the server. This includes connection
90 setup as well as requests made to the backend. The timeout spans 122 setup as well as requests made to the backend. The timeout spans
91 the duration from the moment the first data is written (or 123 the duration from the moment the first data is written (or
92 queued to be written) until all expected responses are returned, 124 queued to be written) until all expected responses are returned,
93 but is postponed for "timeout" seconds each time more data is 125 but is postponed for "timeout" seconds each time more data is
94 returned from the server. If the timer ever goes off then a 126 returned from the server. If the timer ever goes off then a
95 fatal error is generated. If you have an on_error handler 127 fatal error is generated. If you have an "on_error" handler
96 installed, then it will be called, otherwise your program will 128 installed, then it will be called, otherwise your program will
97 die(). 129 die().
98 130
99 When altering your databases with timeouts it is wise to use 131 When altering your databases with timeouts it is wise to use
100 transactions. If you quit due to timeout while performing 132 transactions. If you quit due to timeout while performing
… …
103 complicating recovery. 135 complicating recovery.
104 136
105 Timeout errors are always fatal. 137 Timeout errors are always fatal.
106 138
107 Any additional key-value pairs will be rolled into a hash reference 139 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 140 and passed as the final argument to the "DBI->connect (...)" call.
109 example, to supress errors on STDERR and send them instead to an 141 For example, to suppress errors on STDERR and send them instead to
110 AnyEvent::Handle you could do: 142 an AnyEvent::Handle you could do:
111 143
112 $dbh = new AnyEvent::DBI 144 $dbh = new AnyEvent::DBI
113 "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "", 145 "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "",
114 PrintError => 0, 146 PrintError => 0,
147 on_error => sub {
115 on_error => sub { $log_handle->push_write("DBI Error: $@ at $_[1]:$_[2]\n"); } 148 $log_handle->push_write ("DBI Error: $@ at $_[1]:$_[2]\n");
149 };
116 150
117 $dbh->on_error ( $cb->($dbh, $filename, $line, $fatal) ); 151 $dbh->on_error ($cb->($dbh, $filename, $line, $fatal))
118 Sets (or clears) the on_error handler. 152 Sets (or clears, with "undef") the "on_error" handler.
119 153
120 $dbh->on_connect ( $cb->($dbh) ) ;
121 Sets (or clears) the on_connect handler.
122
123 $dbh->timeout ( $seconds ) ; 154 $dbh->timeout ($seconds)
124 Sets (or clears) the database timeout. Useful to extend the timeout 155 Sets (or clears, with "undef") the database timeout. Useful to
125 when you are about to make a really long query. 156 extend the timeout when you are about to make a really long query.
126 157
158 $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
127 $dbh->exec ("statement", @args, $cb->($dbh, \@rows, \%metadata )) 170 $dbh->exec ("statement", @args, $cb->($dbh, \@rows, $rv))
128 Executes the given SQL statement with placeholders replaced by 171 Executes the given SQL statement with placeholders replaced by
129 @args. The statement will be prepared and cached on the server side, 172 @args. The statement will be prepared and cached on the server side,
130 so using placeholders is compulsory. 173 so using placeholders is extremely important.
131 174
132 The callback will be called with a weakened AnyEvent::DBI object as 175 The callback will be called with a weakened AnyEvent::DBI object as
133 the first argument and the result of "fetchall_arrayref" as (or 176 the first argument and the result of "fetchall_arrayref" as (or
134 "undef" if the statement wasn't a select statement) as the second 177 "undef" if the statement wasn't a select statement) as the second
135 argument. Third argument is a hash reference holding metadata about 178 argument.
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 179
180 Third argument is the return value from the "DBI->execute" method
181 call.
182
140 If an error occurs and the "on_error" callback returns, then no 183 If an error occurs and the "on_error" callback returns, then only
141 arguments will be passed and $@ contains the error message. 184 $dbh will be passed and $@ contains the error message.
185
186 $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
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
242 # otherwise, we can ignore $rc and $errcode for this particular func
142 243
143SEE ALSO 244SEE ALSO
144 AnyEvent, DBI. 245 AnyEvent, DBI, Coro::Mysql.
145 246
146AUTHOR 247AUTHOR AND CONTACT
147 Marc Lehmann <schmorp@schmorp.de> 248 Marc Lehmann <schmorp@schmorp.de> (current maintainer)
148 http://home.schmorp.de/ 249 http://home.schmorp.de/
149 250
150 Adam Rosenstein <adam@redcondor.com> 251 Adam Rosenstein <adam@redcondor.com>
151 http://www.redcondor.com/ 252 http://www.redcondor.com/
152 253

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines