1 | NAME |
1 | NAME |
2 | AnyEvent::DBI - asynchronous DBI access |
2 | AnyEvent::DBI - asynchronous DBI access |
3 | |
3 | |
4 | SYNOPSIS |
4 | SYNOPSIS |
5 | use AnyEvent::DBI; |
5 | use AnyEvent::DBI; |
|
|
6 | |
|
|
7 | 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 | my ($rows, $rv) = @_; |
|
|
13 | |
|
|
14 | print "@$_\n" |
|
|
15 | for @$rows; |
|
|
16 | |
|
|
17 | $cv->broadcast; |
|
|
18 | }); |
|
|
19 | |
|
|
20 | # asynchronously do sth. else here |
|
|
21 | |
|
|
22 | $cv->wait; |
6 | |
23 | |
7 | DESCRIPTION |
24 | DESCRIPTION |
8 | 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 |
9 | run a supported event loop. |
26 | run a supported event loop. |
10 | |
27 | |
… | |
… | |
12 | separate "DBI-Server" processes and sending them requests. |
29 | separate "DBI-Server" processes and sending them requests. |
13 | |
30 | |
14 | 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. |
15 | |
32 | |
16 | The overhead for very simple statements ("select 0") is somewhere around |
33 | The overhead for very simple statements ("select 0") is somewhere around |
17 | 120% to 200% (single/dual core CPU) compared to an explicit |
34 | 120% to 200% (dual/single core CPU) compared to an explicit |
18 | prepare_cached/execute/fetchrow_arrayref/finish combination. |
35 | prepare_cached/execute/fetchrow_arrayref/finish combination. |
19 | |
36 | |
20 | METHODS |
37 | METHODS |
21 | $dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]... |
38 | $dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]... |
22 | Returns a database handle for the given database. Each database |
39 | Returns a database handle for the given database. Each database |
… | |
… | |
37 | on_error => $callback->($dbh, $filename, $line, $fatal) |
54 | on_error => $callback->($dbh, $filename, $line, $fatal) |
38 | When an error occurs, then this callback will be invoked. On |
55 | When an error occurs, then this callback will be invoked. On |
39 | entry, $@ is set to the error message. $filename and $line is |
56 | entry, $@ is set to the error message. $filename and $line is |
40 | where the original request was submitted. |
57 | where the original request was submitted. |
41 | |
58 | |
42 | If this callback returns and this was a fatal error ($fatal is |
59 | If the fatal argument is true then the database connection shuts |
43 | true) then AnyEvent::DBI die's, otherwise it calls the original |
60 | down and your database handle becomes invalid. All of your |
44 | request callback without any arguments. |
61 | request callbacks are called without any arguments. |
45 | |
62 | |
46 | 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 |
47 | not. |
64 | not. |
48 | |
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 | |
49 | $dbh->exec ("statement", @args, $cb->($rows, %extra)) |
127 | $dbh->exec ("statement", @args, $cb->($dbh, \@rows, \%metadata )) |
50 | Executes the given SQL statement with placeholders replaced by |
128 | Executes the given SQL statement with placeholders replaced by |
51 | @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, |
52 | so using placeholders is compulsory. |
130 | so using placeholders is compulsory. |
53 | |
131 | |
54 | The callback will be called with the result of "fetchall_arrayref" |
132 | The callback will be called with a weakened AnyEvent::DBI object as |
55 | as first argument and possibly a hash reference with additional |
133 | the first argument and the result of "fetchall_arrayref" as (or |
56 | information. |
134 | "undef" if the statement wasn't a select statement) as the second |
|
|
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. |
57 | |
139 | |
58 | 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 |
59 | arguments will be passed and $@ contains the error message. |
141 | arguments will be passed and $@ contains the error message. |
60 | |
142 | |
61 | SEE ALSO |
143 | SEE ALSO |
… | |
… | |
63 | |
145 | |
64 | AUTHOR |
146 | AUTHOR |
65 | Marc Lehmann <schmorp@schmorp.de> |
147 | Marc Lehmann <schmorp@schmorp.de> |
66 | http://home.schmorp.de/ |
148 | http://home.schmorp.de/ |
67 | |
149 | |
|
|
150 | Adam Rosenstein <adam@redcondor.com> |
|
|
151 | http://www.redcondor.com/ |
|
|
152 | |