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.5 by root, Mon Jun 29 08:25:05 2009 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 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
143SEE ALSO 227SEE ALSO
144 AnyEvent, DBI. 228 AnyEvent, DBI, Coro::Mysql.
145 229
146AUTHOR 230AUTHOR
147 Marc Lehmann <schmorp@schmorp.de> 231 Marc Lehmann <schmorp@schmorp.de>
148 http://home.schmorp.de/ 232 http://home.schmorp.de/
149 233

Diff Legend

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