6 @EXPORT = qw(conv_i conv_date conv_dateq do_query selectrow_query do_statement
7 dump_query quote_db_date
8 selectfirst_hashref_query selectfirst_array_query
9 selectall_hashref_query selectall_array_query
10 prepare_execute_query prepare_query);
13 my ($value, $default) = @_;
14 return (defined($value) && "$value" ne "") ? $value * 1 : $default;
19 return (defined($value) && "$value" ne "") ? $value : undef;
24 if (defined($value) && "$value" ne "") {
25 $value =~ s/\'/\'\'/g;
32 $main::lxdebug->enter_sub(2);
34 my ($form, $dbh, $query) = splice(@_, 0, 3);
36 dump_query(LXDebug::QUERY, '', $query, @_);
38 if (0 == scalar(@_)) {
39 $dbh->do($query) || $form->dberror($query);
41 $dbh->do($query, undef, @_) ||
42 $form->dberror($query . " (" . join(", ", @_) . ")");
45 $main::lxdebug->leave_sub(2);
48 sub selectrow_query { &selectfirst_array_query }
51 $main::lxdebug->enter_sub(2);
53 my ($form, $sth, $query) = splice(@_, 0, 3);
55 dump_query(LXDebug::QUERY, '', $query, @_);
57 if (0 == scalar(@_)) {
58 $sth->execute() || $form->dberror($query);
61 $form->dberror($query . " (" . join(", ", @_) . ")");
64 $main::lxdebug->leave_sub(2);
68 my ($level, $msg, $query) = splice(@_, 0, 3);
70 while ($query =~ /\?/) {
71 my $value = shift(@_);
72 $value =~ s/\'/\\\'/g;
73 $value = "'${value}'";
74 $query =~ s/\?/$value/;
77 $query =~ s/[\n\s]+/ /g;
79 $msg .= " " if ($msg);
81 $main::lxdebug->message($level, $msg . $query);
87 return "NULL" unless defined $str;
88 return "current_date" if $str =~ /current_date/;
95 $main::lxdebug->enter_sub(2);
97 my ($form, $dbh, $query) = splice(@_, 0, 3);
99 dump_query(LXDebug::QUERY, '', $query, @_);
101 my $sth = $dbh->prepare($query) || $form->dberror($query);
103 $main::lxdebug->leave_sub(2);
108 sub prepare_execute_query {
109 $main::lxdebug->enter_sub(2);
111 my ($form, $dbh, $query) = splice(@_, 0, 3);
113 dump_query(LXDebug::QUERY, '', $query, @_);
115 my $sth = $dbh->prepare($query) || $form->dberror($query);
116 if (scalar(@_) != 0) {
117 $sth->execute(@_) || $form->dberror($query . " (" . join(", ", @_) . ")");
119 $sth->execute() || $form->dberror($query);
122 $main::lxdebug->leave_sub(2);
127 sub selectall_hashref_query {
128 $main::lxdebug->enter_sub(2);
130 my ($form, $dbh, $query) = splice(@_, 0, 3);
132 my $sth = prepare_execute_query($form, $dbh, $query, @_);
134 while (my $ref = $sth->fetchrow_hashref()) {
135 push(@{ $result }, $ref);
139 $main::lxdebug->leave_sub(2);
144 sub selectall_array_query {
145 $main::lxdebug->enter_sub(2);
147 my ($form, $dbh, $query) = splice(@_, 0, 3);
149 my $sth = prepare_execute_query($form, $dbh, $query, @_);
151 while (my ($value) = $sth->fetchrow_array()) {
152 push(@result, $value);
156 $main::lxdebug->leave_sub(2);
161 sub selectfirst_hashref_query {
162 $main::lxdebug->enter_sub(2);
164 my ($form, $dbh, $query) = splice(@_, 0, 3);
166 my $sth = prepare_execute_query($form, $dbh, $query, @_);
167 my $ref = $sth->fetchrow_hashref();
170 $main::lxdebug->leave_sub(2);
175 sub selectfirst_array_query {
176 $main::lxdebug->enter_sub(2);
178 my ($form, $dbh, $query) = splice(@_, 0, 3);
180 my $sth = prepare_execute_query($form, $dbh, $query, @_);
181 my @ret = $sth->fetchrow_array();
184 $main::lxdebug->leave_sub(2);
196 SL::DBUTils.pm: All about Databaseconections in Lx
202 conv_i($str, $default)
207 do_query($form, $dbh, $query)
208 do_statement($form, $sth, $query)
210 dump_query($level, $msg, $query)
211 prepare_execute_query($form, $dbh, $query)
213 my $all_results_ref = selectall_hashref_query($form, $dbh, $query)
214 my $first_result_hash_ref = selectfirst_hashref_query($form, $dbh, $query);
216 my @first_result = selectfirst_array_query($form, $dbh, $query); # ==
217 my @first_result = selectrow_query($form, $dbh, $query);
222 DBUtils is the attempt to reduce the amount of overhead it takes to retrieve information from the database in Lx-Office. Previously it would take about 15 lines of code just to get one single integer out of the database, including failure procedures and importing the necessary packages. Debugging would take even more.
224 Using DBUtils most database procedures can be reduced to defining the query, executing it, and retrieving the result. Let DBUtils handle the rest. Whenever there is a database operation not covered in DBUtils, add it here, rather than working around it in the backend code.
226 DBUtils relies heavily on two parameters which have to be passed to almost every function: $form and $dbh.
227 - $form is used for error handling only. It can be omitted in theory, but should not.
228 - $dbh is a handle to the databe, as returned by the DBI::connect routine. If you don't have an active connectiong, you can query $form->get_standard_dbh() to get a generic no_auto connection. Don't forget to commit in this case!
231 Every function here should accomplish the follwing things:
232 - Easy debugging. Every handled query gets dumped via LXDebug, if specified there.
233 - Safe value binding. Although DBI is far from perfect in terms of binding, the rest of the bindings should happen here.
234 - Error handling. Should a query fail, an error message will be generated here instead of in the backend code invoking DBUtils.
236 Note that binding is not perfect here either...
238 =head2 QUOTING FUNCTIONS
244 =item conv_i STR,DEFAULT
246 Converts STR to an integer. If STR is empty, returns DEFAULT. If no DEFAULT is given, returns undef.
250 Converts STR to a date string. If STR is emptry, returns undef.
254 Database version of conv_date. Quotes STR before returning. Returns 'NULL' if STR is empty.
256 =item quote_db_date STR
258 Treats STR as a database date, quoting it. If STR equals current_date returns an escaped version which is treated as the current date by Postgres.
259 Returns 'NULL' if STR is empty.
263 =head2 QUERY FUNCTIONS
267 =item do_query FORM,DBH,QUERY,ARRAY
269 Uses DBI::do to execute QUERY on DBH using ARRAY for binding values. FORM is only needed for error handling, but should always be passed nevertheless. Use this for insertions or updates that don't need to be prepared.
271 =item do_statement FORM,STH,QUERY,ARRAY
273 Uses DBI::execute to execute QUERY on DBH using ARRAY for binding values. As with do_query, FORM is only used for error handling. If you are unsure what to use, refer to the documentation of DBI::do and DBI::execute.
275 =item prepare_execute_query FORM,DBH,QUERY,ARRAY
277 Prepares and executes QUERY on DBH using DBI::prepare and DBI::execute. ARRAY is passed as binding values to execute.
281 =head2 RETRIEVAL FUNCTIONS
285 =item selectfirst_array_query FORM,DBH,QUERY,ARRAY
287 =item selectrow_query FORM,DBH,QUERY,ARRAY
289 Prepares and executes a query using DBUtils functions, retireves the first row from the database, and returns it as an arrayref of the first row.
291 =item selectfirst_hashref_query FORM,DBH,QUERY,ARRAY
293 Prepares and executes a query using DBUtils functions, retireves the first row from the database, and returns it as a hashref of the first row.
295 =item selectall_hashref_query FORM,DBH,QUERY,ARRAY
297 Prepares and executes a query using DBUtils functions, retireves all data from the database, and returns it in hashref mode. This is slightly confusing, as the data structure will actually be a reference to an array, containing hashrefs for each row.
301 =head2 DEBUG FUNCTIONS
305 =item dump_query LEVEL,MSG,QUERY,ARRAY
307 Dumps a query using LXDebug->message, using LEVEL for the debug-level of LXDebug. If MSG is given, it preceeds the QUERY dump in the logfiles. ARRAY is used to interpolate the '?' placeholders in QUERY, the resulting QUERY can be copy-pasted into a database frontend for debugging. Note that this method is also automatically called by each of the other QUERY FUNCTIONS, so there is in general little need to invoke it manually.
315 =item Retrieving a whole table:
317 $query = qq|SELECT id, pricegroup FROM pricegroup|;
318 $form->{PRICEGROUPS} = selectall_hashref_query($form, $dbh, $query);
320 =item Retrieving a single value:
322 $query = qq|SELECT nextval('glid')|;
323 ($new_id) = selectrow_query($form, $dbh, $query);
325 =item Using binding values:
327 $query = qq|UPDATE ar SET paid = amount + paid, storno = 't' WHERE id = ?|;
328 do_query($form, $dbh, $query, $id);
330 =item A more complicated example, using dynamic binding values:
334 if ($form->{language_values} ne "") {
335 $query = qq|SELECT l.id, l.description, tr.translation, tr.longdescription
337 LEFT OUTER JOIN translation tr ON (tr.language_id = l.id) AND (tr.parts_id = ?)|;
338 @values = (conv_i($form->{id}));
340 $query = qq|SELECT id, description FROM language|;
343 my $languages = selectall_hashref_query($form, $dbh, $query, @values);
349 =head1 MODULE AUTHORS
351 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
352 Sven Schoeling E<lt>s.schoeling@linet-services.deE<gt>
354 =head1 DOCUMENTATION AUTHORS
356 Udo Spallek E<lt>udono@gmx.netE<gt>
357 Sven Schoeling E<lt>s.schoeling@linet-services.deE<gt>
359 =head1 COPYRIGHT AND LICENSE
361 Copyright 2007 by Lx-Office Community
363 This program is free software; you can redistribute it and/or modify
364 it under the terms of the GNU General Public License as published by
365 the Free Software Foundation; either version 2 of the License, or
366 (at your option) any later version.
368 This program is distributed in the hope that it will be useful,
369 but WITHOUT ANY WARRANTY; without even the implied warranty of
370 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
371 GNU General Public License for more details.
372 You should have received a copy of the GNU General Public License
373 along with this program; if not, write to the Free Software
374 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.