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

Comparing AnyEvent-DBI/README (file contents):
Revision 1.3 by root, Sat Dec 20 21:28:57 2008 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;
… …
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 this callback returns and this was a fatal error ($fatal is 74 If the fatal argument is true then the database connection is
60 true) then AnyEvent::DBI die's, otherwise it calls the original 75 shut down and your database handle became invalid. In addition
61 request callback without any arguments. 76 to invoking the "on_error" callback, all of your queued request
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
82 on_connect => $callback->($dbh[, $success])
83 If you supply an "on_connect" callback, then this callback will
84 be invoked after the database connect attempt. If the connection
85 succeeds, $success is true, otherwise it is missing and $@
86 contains the $DBI::errstr.
87
88 Regardless of whether "on_connect" is supplied, connect errors
89 will result in "on_error" being called. However, if no
90 "on_connect" callback is supplied, then connection errors are
91 considered fatal. The client will "die" and the "on_error"
92 callback will be called with $fatal true.
93
94 When on_connect is supplied, connect error are not fatal and
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).
110
111 timeout => seconds
112 If you supply a timeout parameter (fractional values are
113 supported), then a timer is started any time the DBI handle
114 expects a response from the server. This includes connection
115 setup as well as requests made to the backend. The timeout spans
116 the duration from the moment the first data is written (or
117 queued to be written) until all expected responses are returned,
118 but is postponed for "timeout" seconds each time more data is
119 returned from the server. If the timer ever goes off then a
120 fatal error is generated. If you have an "on_error" handler
121 installed, then it will be called, otherwise your program will
122 die().
123
124 When altering your databases with timeouts it is wise to use
125 transactions. If you quit due to timeout while performing
126 insert, update or schema-altering commands you can end up not
127 knowing if the action was submitted to the database,
128 complicating recovery.
129
130 Timeout errors are always fatal.
131
132 Any additional key-value pairs will be rolled into a hash reference
133 and passed as the final argument to the "DBI->connect (...)" call.
134 For example, to supress errors on STDERR and send them instead to an
135 AnyEvent::Handle you could do:
136
137 $dbh = new AnyEvent::DBI
138 "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "",
139 PrintError => 0,
140 on_error => sub {
141 $log_handle->push_write ("DBI Error: $@ at $_[1]:$_[2]\n");
142 };
143
144 $dbh->on_error ($cb->($dbh, $filename, $line, $fatal))
145 Sets (or clears, with "undef") the "on_error" handler.
146
147 $dbh->timeout ($seconds)
148 Sets (or clears, with "undef") the database timeout. Useful to
149 extend the timeout when you are about to make a really long query.
150
66 $dbh->exec ("statement", @args, $cb->($rows, $rv, ...)) 151 $dbh->exec ("statement", @args, $cb->($dbh, \@rows, $rv))
67 Executes the given SQL statement with placeholders replaced by 152 Executes the given SQL statement with placeholders replaced by
68 @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,
69 so using placeholders is compulsory. 154 so using placeholders is extremely important.
70 155
71 The callback will be called with the result of "fetchall_arrayref" 156 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 157 the first argument and the result of "fetchall_arrayref" as (or
73 statement) and the return value of "execute" as second argument. 158 "undef" if the statement wasn't a select statement) as the second
74 Additional arguments might get passed as well. 159 argument.
75 160
161 Third argument is the return value from the "DBI->execute" method
162 call.
163
76 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
77 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
78 226
79SEE ALSO 227SEE ALSO
80 AnyEvent, DBI. 228 AnyEvent, DBI, Coro::Mysql.
81 229
82AUTHOR 230AUTHOR
83 Marc Lehmann <schmorp@schmorp.de> 231 Marc Lehmann <schmorp@schmorp.de>
84 http://home.schmorp.de/ 232 http://home.schmorp.de/
85 233
234 Adam Rosenstein <adam@redcondor.com>
235 http://www.redcondor.com/
236

Diff Legend

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