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

Comparing AnyEvent-DBI/README (file contents):
Revision 1.2 by root, Mon Jul 21 02:34:40 2008 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 this callback returns and this was a fatal error ($fatal is 75 If the fatal argument is true then the database connection is
60 true) then AnyEvent::DBI die's, otherwise it calls the original 76 shut down and your database handle became invalid. In addition
61 request callback without any arguments. 77 to invoking the "on_error" callback, all of your queued request
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
83 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 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
118 timeout => seconds
119 If you supply a timeout parameter (fractional values are
120 supported), then a timer is started any time the DBI handle
121 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 fatal error is generated. If you have an "on_error" handler
128 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 and passed as the final argument to the "DBI->connect (...)" call.
141 For example, to suppress errors on STDERR and send them instead to
142 an AnyEvent::Handle you could do:
143
144 $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
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
66 $dbh->exec ("statement", @args, $cb->($rows, $rv, ...)) 170 $dbh->exec ("statement", @args, $cb->($dbh, \@rows, $rv))
67 Executes the given SQL statement with placeholders replaced by 171 Executes the given SQL statement with placeholders replaced by
68 @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,
69 so using placeholders is compulsory. 173 so using placeholders is extremely important.
70 174
71 The callback will be called with the result of "fetchall_arrayref" 175 The callback will be called with a weakened AnyEvent::DBI object as
72 as first argument (or "undef" if the statement wasn't a select 176 the first argument and the result of "fetchall_arrayref" as (or
73 statement) and the return value of "execute" as second argument. 177 "undef" if the statement wasn't a select statement) as the second
74 Additional arguments might get passed as well. 178 argument.
75 179
180 Third argument is the return value from the "DBI->execute" method
181 call.
182
76 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
77 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
78 243
79SEE ALSO 244SEE ALSO
80 AnyEvent, DBI. 245 AnyEvent, DBI, Coro::Mysql.
81 246
82AUTHOR 247AUTHOR AND CONTACT
83 Marc Lehmann <schmorp@schmorp.de> 248 Marc Lehmann <schmorp@schmorp.de> (current maintainer)
84 http://home.schmorp.de/ 249 http://home.schmorp.de/
85 250
251 Adam Rosenstein <adam@redcondor.com>
252 http://www.redcondor.com/
253

Diff Legend

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