… | |
… | |
23 | |
23 | |
24 | DESCRIPTION |
24 | DESCRIPTION |
25 | This module is an AnyEvent user, you need to make sure that you use and |
25 | This module is an AnyEvent user, you need to make sure that you use and |
26 | run a supported event loop. |
26 | run a supported event loop. |
27 | |
27 | |
28 | This module implements asynchronous DBI access by forking or executing |
28 | This module implements asynchronous DBI access my forking or executing |
29 | separate "DBI-Server" processes and sending them requests. |
29 | separate "DBI-Server" processes and sending them requests. |
30 | |
30 | |
31 | It means that you can run DBI requests in parallel to other tasks. |
31 | It means that you can run DBI requests in parallel to other tasks. |
32 | |
32 | |
33 | The overhead for very simple statements ("select 0") is somewhere around |
33 | The overhead for very simple statements ("select 0") is somewhere around |
… | |
… | |
54 | on_error => $callback->($dbh, $filename, $line, $fatal) |
54 | on_error => $callback->($dbh, $filename, $line, $fatal) |
55 | When an error occurs, then this callback will be invoked. On |
55 | When an error occurs, then this callback will be invoked. On |
56 | entry, $@ is set to the error message. $filename and $line is |
56 | entry, $@ is set to the error message. $filename and $line is |
57 | where the original request was submitted. |
57 | where the original request was submitted. |
58 | |
58 | |
59 | If this callback returns and this was a fatal error ($fatal is |
59 | If the fatal argument is true then the database connection shuts |
60 | true) then AnyEvent::DBI die's, otherwise it calls the original |
60 | down and your database handle becomes invalid. All of your |
61 | request callback without any arguments. |
61 | request callbacks are called without any arguments. |
62 | |
62 | |
63 | If omitted, then "die" will be called on any errors, fatal or |
63 | If omitted, then "die" will be called on any errors, fatal or |
64 | not. |
64 | not. |
65 | |
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 | |
66 | $dbh->exec ("statement", @args, $cb->($rows, $rv, ...)) |
127 | $dbh->exec ("statement", @args, $cb->($dbh, \@rows, \%metadata )) |
67 | Executes the given SQL statement with placeholders replaced by |
128 | Executes the given SQL statement with placeholders replaced by |
68 | @args. The statement will be prepared and cached on the server side, |
129 | @args. The statement will be prepared and cached on the server side, |
69 | so using placeholders is compulsory. |
130 | so using placeholders is compulsory. |
70 | |
131 | |
71 | The callback will be called with the result of "fetchall_arrayref" |
132 | 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 |
133 | the first argument and the result of "fetchall_arrayref" as (or |
73 | statement) and the return value of "execute" as second argument. |
134 | "undef" if the statement wasn't a select statement) as the second |
74 | Additional arguments might get passed as well. |
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. |
75 | |
139 | |
76 | If an error occurs and the "on_error" callback returns, then no |
140 | If an error occurs and the "on_error" callback returns, then no |
77 | arguments will be passed and $@ contains the error message. |
141 | arguments will be passed and $@ contains the error message. |
78 | |
142 | |
79 | SEE ALSO |
143 | SEE ALSO |
… | |
… | |
81 | |
145 | |
82 | AUTHOR |
146 | AUTHOR |
83 | Marc Lehmann <schmorp@schmorp.de> |
147 | Marc Lehmann <schmorp@schmorp.de> |
84 | http://home.schmorp.de/ |
148 | http://home.schmorp.de/ |
85 | |
149 | |
|
|
150 | Adam Rosenstein <adam@redcondor.com> |
|
|
151 | http://www.redcondor.com/ |
|
|
152 | |