… | |
… | |
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 | |
24 | DESCRIPTION |
26 | DESCRIPTION |
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 | The overhead for very simple statements ("select 0") is somewhere around |
34 | 120% to 200% (dual/single core CPU) compared to an explicit |
36 | 120% to 200% (dual/single core CPU) compared to an explicit |
35 | prepare_cached/execute/fetchrow_arrayref/finish combination. |
37 | prepare_cached/execute/fetchrow_arrayref/finish combination. |
|
|
38 | |
|
|
39 | ERROR HANDLING |
|
|
40 | This module defines a number of functions that accept a callback |
|
|
41 | argument. All callbacks used by this module get their AnyEvent::DBI |
|
|
42 | handle object passed as first argument. |
|
|
43 | |
|
|
44 | If the request was successful, then there will be more arguments, |
|
|
45 | otherwise there will only be the $dbh argument and $@ contains an error |
|
|
46 | message. |
|
|
47 | |
|
|
48 | A convinient way to check whether an error occured is to check $#_ - if |
|
|
49 | that is true, then the function was successful, otherwise there was an |
|
|
50 | error. |
36 | |
51 | |
37 | METHODS |
52 | METHODS |
38 | $dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]... |
53 | $dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]... |
39 | Returns a database handle for the given database. Each database |
54 | Returns a database handle for the given database. Each database |
40 | handle has an associated server process that executes statements in |
55 | handle has an associated server process that executes statements in |
… | |
… | |
54 | on_error => $callback->($dbh, $filename, $line, $fatal) |
69 | on_error => $callback->($dbh, $filename, $line, $fatal) |
55 | When an error occurs, then this callback will be invoked. On |
70 | When an error occurs, then this callback will be invoked. On |
56 | entry, $@ is set to the error message. $filename and $line is |
71 | entry, $@ is set to the error message. $filename and $line is |
57 | where the original request was submitted. |
72 | where the original request was submitted. |
58 | |
73 | |
59 | If the fatal argument is true then the database connection shuts |
74 | If the fatal argument is true then the database connection is |
60 | down and your database handle becomes invalid. All of your |
75 | shut down and your database handle became invalid. In addition |
|
|
76 | to invoking the "on_error" callback, all of your queued request |
61 | request callbacks are called without any arguments. |
77 | callbacks are called without only the $dbh argument. |
62 | |
78 | |
63 | If omitted, then "die" will be called on any errors, fatal or |
79 | If omitted, then "die" will be called on any errors, fatal or |
64 | not. |
80 | not. |
65 | |
81 | |
66 | The $dbh argument is always a weak reference to the |
|
|
67 | AnyEvent::DBI object. |
|
|
68 | |
|
|
69 | on_connect => $callback->($dbh) |
82 | on_connect => $callback->($dbh[, $success]) |
70 | If you supply an on_connect callback, then this callback will be |
83 | If you supply an "on_connect" callback, then this callback will |
71 | invoked after the database connection is attempted. If the |
84 | be invoked after the database connect attempt. If the connection |
72 | connection succeeds, $dbh contains a weak reference to the |
85 | 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. |
86 | contains the $DBI::errstr. |
76 | |
87 | |
77 | Regardless of whether on_connect is supplied, connect errors |
88 | Regardless of whether "on_connect" is supplied, connect errors |
78 | will result in on_error being called. However, if no on_connect |
89 | will result in "on_error" being called. However, if no |
79 | callback is supplied, then connection errors are considered |
90 | "on_connect" callback is supplied, then connection errors are |
80 | fatal. The client will die() and the on_error callback will be |
91 | considered fatal. The client will "die" and the "on_error" |
81 | called with $fatal true. When on_connect is supplied, connect |
92 | callback will be called with $fatal true. |
82 | error are not fatal and AnyEvent::DBI will not die(). You still |
93 | |
83 | cannot, however, use the $dbh object you recived from new() to |
94 | When on_connect is supplied, connect error are not fatal and |
84 | make requests. |
95 | AnyEvent::DBI will not "die". You still cannot, however, use the |
|
|
96 | $dbh object you received from "new" to make requests. |
|
|
97 | |
|
|
98 | exec_server => 1 |
|
|
99 | If you supply an "exec_server" argument, then the DBI server |
|
|
100 | process will fork and exec another perl interpreter (using $^X) |
|
|
101 | with just the AnyEvent::DBI proxy running. This will provide the |
|
|
102 | cleanest possible porxy for your database server. |
|
|
103 | |
|
|
104 | If you do not supply the "exec_server" argument (or supply it |
|
|
105 | with a false value) then the traditional method of starting the |
|
|
106 | server by forking the current process is used. The forked |
|
|
107 | interpreter will try to clean itself up by calling POSIX::close |
|
|
108 | on all file descriptors except STDIN, STDOUT, and STDERR (and |
|
|
109 | the socket it uses to communicate with the cilent, of course). |
85 | |
110 | |
86 | timeout => seconds |
111 | timeout => seconds |
87 | If you supply a timeout parameter (floating point number of |
112 | If you supply a timeout parameter (fractional values are |
88 | seconds), then a timer is started any time the DBI handle |
113 | supported), then a timer is started any time the DBI handle |
89 | expects a response from the server. This includes connection |
114 | expects a response from the server. This includes connection |
90 | setup as well as requests made to the backend. The timeout spans |
115 | setup as well as requests made to the backend. The timeout spans |
91 | the duration from the moment the first data is written (or |
116 | the duration from the moment the first data is written (or |
92 | queued to be written) until all expected responses are returned, |
117 | queued to be written) until all expected responses are returned, |
93 | but is postponed for "timeout" seconds each time more data is |
118 | but is postponed for "timeout" seconds each time more data is |
94 | returned from the server. If the timer ever goes off then a |
119 | returned from the server. If the timer ever goes off then a |
95 | fatal error is generated. If you have an on_error handler |
120 | fatal error is generated. If you have an "on_error" handler |
96 | installed, then it will be called, otherwise your program will |
121 | installed, then it will be called, otherwise your program will |
97 | die(). |
122 | die(). |
98 | |
123 | |
99 | When altering your databases with timeouts it is wise to use |
124 | When altering your databases with timeouts it is wise to use |
100 | transactions. If you quit due to timeout while performing |
125 | transactions. If you quit due to timeout while performing |
… | |
… | |
103 | complicating recovery. |
128 | complicating recovery. |
104 | |
129 | |
105 | Timeout errors are always fatal. |
130 | Timeout errors are always fatal. |
106 | |
131 | |
107 | Any additional key-value pairs will be rolled into a hash reference |
132 | 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 |
133 | and passed as the final argument to the "DBI->connect (...)" call. |
109 | example, to supress errors on STDERR and send them instead to an |
134 | For example, to supress errors on STDERR and send them instead to an |
110 | AnyEvent::Handle you could do: |
135 | AnyEvent::Handle you could do: |
111 | |
136 | |
112 | $dbh = new AnyEvent::DBI |
137 | $dbh = new AnyEvent::DBI |
113 | "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "", |
138 | "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "", |
114 | PrintError => 0, |
139 | PrintError => 0, |
|
|
140 | on_error => sub { |
115 | on_error => sub { $log_handle->push_write("DBI Error: $@ at $_[1]:$_[2]\n"); } |
141 | $log_handle->push_write ("DBI Error: $@ at $_[1]:$_[2]\n"); |
|
|
142 | }; |
116 | |
143 | |
117 | $dbh->on_error ( $cb->($dbh, $filename, $line, $fatal) ); |
144 | $dbh->on_error ($cb->($dbh, $filename, $line, $fatal)) |
118 | Sets (or clears) the on_error handler. |
145 | Sets (or clears, with "undef") the "on_error" handler. |
119 | |
146 | |
120 | $dbh->on_connect ( $cb->($dbh) ) ; |
|
|
121 | Sets (or clears) the on_connect handler. |
|
|
122 | |
|
|
123 | $dbh->timeout ( $seconds ) ; |
147 | $dbh->timeout ($seconds) |
124 | Sets (or clears) the database timeout. Useful to extend the timeout |
148 | Sets (or clears, with "undef") the database timeout. Useful to |
125 | when you are about to make a really long query. |
149 | extend the timeout when you are about to make a really long query. |
126 | |
150 | |
127 | $dbh->exec ("statement", @args, $cb->($dbh, \@rows, \%metadata )) |
151 | $dbh->exec ("statement", @args, $cb->($dbh, \@rows, $rv)) |
128 | Executes the given SQL statement with placeholders replaced by |
152 | Executes the given SQL statement with placeholders replaced by |
129 | @args. The statement will be prepared and cached on the server side, |
153 | @args. The statement will be prepared and cached on the server side, |
130 | so using placeholders is compulsory. |
154 | so using placeholders is extremely important. |
131 | |
155 | |
132 | The callback will be called with a weakened AnyEvent::DBI object as |
156 | The callback will be called with a weakened AnyEvent::DBI object as |
133 | the first argument and the result of "fetchall_arrayref" as (or |
157 | the first argument and the result of "fetchall_arrayref" as (or |
134 | "undef" if the statement wasn't a select statement) as the second |
158 | "undef" if the statement wasn't a select statement) as the second |
135 | argument. Third argument is a hash reference holding metadata about |
159 | 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 | |
160 | |
|
|
161 | Third argument is the return value from the "DBI->execute" method |
|
|
162 | call. |
|
|
163 | |
140 | If an error occurs and the "on_error" callback returns, then no |
164 | If an error occurs and the "on_error" callback returns, then only |
141 | arguments will be passed and $@ contains the error message. |
165 | $dbh will be passed and $@ contains the error message. |
|
|
166 | |
|
|
167 | $dbh->attr ($attr_name[, $attr_value], $cb->($dbh, $new_value)) |
|
|
168 | An accessor for the handle attributes, such as "AutoCommit", |
|
|
169 | "RaiseError", "PrintError" and so on. If you provide an $attr_value |
|
|
170 | (which might be "undef"), then the given attribute will be set to |
|
|
171 | that value. |
|
|
172 | |
|
|
173 | The callback will be passed the database handle and the attribute's |
|
|
174 | value if successful. |
|
|
175 | |
|
|
176 | If an error occurs and the "on_error" callback returns, then only |
|
|
177 | $dbh will be passed and $@ contains the error message. |
|
|
178 | |
|
|
179 | $dbh->begin_work ($cb->($dbh[, $rc])) |
|
|
180 | $dbh->commit ($cb->($dbh[, $rc])) |
|
|
181 | $dbh->rollback ($cb->($dbh[, $rc])) |
|
|
182 | The begin_work, commit, and rollback methods expose the equivalent |
|
|
183 | transaction control method of the DBI driver. On success, $rc is |
|
|
184 | true. |
|
|
185 | |
|
|
186 | If an error occurs and the "on_error" callback returns, then only |
|
|
187 | $dbh will be passed and $@ contains the error message. |
|
|
188 | |
|
|
189 | $dbh->func ('string_which_yields_args_when_evaled', $func_name, |
|
|
190 | $cb->($dbh, $rc, $dbi_err, $dbi_errstr)) |
|
|
191 | This gives access to database driver private methods. Because they |
|
|
192 | are not standard you cannot always depend on the value of $rc or |
|
|
193 | $dbi_err. Check the documentation for your specific driver/function |
|
|
194 | combination to see what it returns. |
|
|
195 | |
|
|
196 | Note that the first argument will be eval'ed to produce the argument |
|
|
197 | list to the func() method. This must be done because the |
|
|
198 | serialization protocol between the AnyEvent::DBI server process and |
|
|
199 | your program does not support the passage of closures. |
|
|
200 | |
|
|
201 | Here's an example to extend the query language in SQLite so it |
|
|
202 | supports an intstr() function: |
|
|
203 | |
|
|
204 | $cv = AnyEvent->condvar; |
|
|
205 | $dbh->func ( |
|
|
206 | q{ |
|
|
207 | instr => 2, sub { |
|
|
208 | my ($string, $search) = @_; |
|
|
209 | return index $string, $search; |
|
|
210 | }, |
|
|
211 | }, |
|
|
212 | create_function => sub { |
|
|
213 | return $cv->send ($@) |
|
|
214 | unless $#_; |
|
|
215 | $cv->send (undef, @_[1,2,3]); |
|
|
216 | } |
|
|
217 | ); |
|
|
218 | |
|
|
219 | my ($err,$rc,$errcode,$errstr) = $cv->recv; |
|
|
220 | |
|
|
221 | die $err if defined $err; |
|
|
222 | die "EVAL failed: $errstr" |
|
|
223 | if $errcode; |
|
|
224 | |
|
|
225 | # otherwise, we can ignore $rc and $errcode for this particular func |
142 | |
226 | |
143 | SEE ALSO |
227 | SEE ALSO |
144 | AnyEvent, DBI. |
228 | AnyEvent, DBI, Coro::Mysql. |
145 | |
229 | |
146 | AUTHOR |
230 | AUTHOR |
147 | Marc Lehmann <schmorp@schmorp.de> |
231 | Marc Lehmann <schmorp@schmorp.de> |
148 | http://home.schmorp.de/ |
232 | http://home.schmorp.de/ |
149 | |
233 | |