/ 
Tools-0.04
/ Tools::SQL

NAME

Tools::SQL - sql execution made easy

SYNOPSIS

use Tools::SQL;
use DBI;

my $dbh = DBI->connect($data_source, $username, $auth, \%attr);


### do a multiple insert into a table with a single statement
my $sql = 'insert into some_table (thing,stuff) values (?,?)';

my @vals = ( [qw|foo bar|], [qw|zot quux|] );

my $bool = $dbh->exec_sql( $sql, \@vals );


### execute a query and get the statement handler back on success
my $sql = 'select * from some_table where thing = ?';

my $sth = $dbh->exec_sql( $sql, 'something' )
                or warn qq[Could not execute '$sql'];

### now do stuff with $sth
while( $sth->fetchrow_hashref ) { ... }

### don't forget to call finish() when you got a $sth back
$sth->finish;


### don't have Tools::SQL issue warnings -- default is '1'
$Tools::SQL::VERBOSE = 0;

### make errors fatal -- default is '0'
$Tools::SQL::FATAL = 1;

DESCRIPTION

Tools::SQL is a transparent way of eliminating the overhead of having to first prepare a statement, check if it prepared correctly, then execute a query and check if a if executed correctly.

Simply hand it the SQL you want executed and any arguments you need to be passed to fill the placeholders and Tools::SQL will just DWYM.

How it works

Tools::SQL places itself at the back of your databasedrivers @ISA array, so you can call it's functions through your database handler.

Tools::SQL currently only provides one method, namely exec_sql

Methods

exec_sql

exec_sql takes the following arguments:

  • A string containing the sql you want executed, containing any placeholders where necessary.

  • Either a list or a reference to a list of lists with arguments that will serve to be substituted for the placeholders.

When providing a list of arguments, exec_sql assumes you only want to do one insert and will return you a statement handler upon success, or undef upon failure of the execution.

When you provide a reference to a list of lists, exec_sql assumes you want to execute the statement multiple times, once for each list. It will then return true if all executions went well, or undef if one or more of them failed.

Global Variables

The behaviour of Tools::SQL can be altered by changing the following global variables:

$Tools::SQL::VERBOSE

This controls whether Tools::SQL will issue warnings and explenations as to why certain things may have failed. If you set it to 0, Tools::SQL will not output anything. The default is 1;

$Tools::SQL::FATAL

This controls whether failures for executing statements via Tools::SQL should be considered fatal or not. When set to 1, whenever a statement fails, Tools::SQL will die with it's error message.

The default is 0;

See Also

DBI

Todo

Inline::SQL?

AUTHOR

This module by Jos Boumans <kane@cpan.org>.

COPYRIGHT

This module is copyright (c) 2002 Jos Boumans <kane@cpan.org>. All rights reserved.

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.