/ 
DBIx-0.02
/ DBIx

NAME

DBIx - concise SQL-based DBI usage

SYNOPSIS

 use DBIx;

my $col  = one_col       $sql, @bind ;
my @col  = one_col       $sql, @bind ;

my $row  = one_row       $sql, @bind ;
my @row  = one_row       $sql, @bind ;
my $row  = one_row_href  $sql, @bind ;

my @rows = all_rows      $sql, @bind ;
my @rows = all_rows_href $sql, @bind ;

my $sth  = sql_do        $sql, @bind ;

my $date = sql_date;	# calculated from now
my $date = sql_date_from_href
 { year   => 1969,
   month  => 5,
   day    => 11,
   hours  => 5,        # defaults to 00 if not specified
   minutes => 12,	# defaults to 00 if not specified
   seconds => 35	# defaults to 00 if not specified
 } ;

begin_transaction;
 # some SQL activities ...
commit_transaction;
 # or maybe
rollback_transaction;

DESTROY {
 if (my $count = hung_transactions) {
   warn "DBH is going out of scope with unbalanced begin_tran/commit call count of $count";
 }

DESCRIPTION

DBIx provides a convenient meta-layer for DBI usage. Actually, to be honest DBIx provides code written by Matt Seargent in the Example::DB::Default of DBIx::AnyDBD. However, most of that code was of such obvious general utility that I decided to rip it out and make it generally useful. In doing so, I decided to make the passing of a database handle to the API functions optional and provide a means of searching for a pre-created handle. This is an idea borrowed from PApp::SQL, an excellent DBI meta-layer.

The synopsis should make it clear how to use this package. The only other thing that requires not is that undef is returned when the requested data cannot be retrieved, e.g:

 my $row  = one_row_href 'SELECT * FROM user WHERE email = ?', $email;
$row or die "no user has email $email";

Oh and one more thing. I will discuss how database handles are found so that the API functions can actually do database work.

LOOKING UP DATABASE HANDLES

All API functions shown in the SYNOPSIS actually take an argument just after the function name which must be a viable DBI database handle. However, this argument is optional and if it does not exist then a search is made for a database handle as follows:

1 it looks in the current package for a package wariable $DBH
2 it looks in the for a package wariable $DBIx::DBH

Thus the following call:

my $col  = one_col       $sql, @bind ;

which performs the documented lookup described above could actually be:

my $col  = one_col       $dbh, $sql, @bind ;

and eliminate the lookup.

EXPORT

All the things listed in the SYNOPSIS are exported.

AUTHOR

T. M. Brannon, <tbone@cpan.org>

Shamelessly stolen from Matt Seargent's Example::DB::Default code in DBIx::AnyDBD

SEE ALSO

DBIx::AnyDBD, PApp::SQL, DBIx::Broker, DBIx::Easy, EZDBI, DBIx::DWIW, DBIx::Abstract, DBIx::AbstractLite, and the DBIx and SQL hierarchies on http://kobesearch.CPAN.org