NAME

DBIx::Broker - a little layer somewhere between top-level code and raw DBI calls

SYNOPSIS

use DBIx::Broker;

$db  =  DBIx::Broker->new( $DBI_driver, $database, $hostname, $port, $user, $password );

$db  =  DBIx::Broker->new( );

$db->is_active( );

$db->set_db_handle( $classic_dbi_handle );
$classic_dbi_handle  =  $db->get_db_handle( );

$another_db_obj  =  $db->clone();

$db->debug_on( \*DEBUG_OUTPUT_HANDLE );
$db->debug_off( );

@query_results  =  $db->select( \@desired_fields, \@desired_tables, $stipulations, $hash_or_not );
@query_results  =  $db->select( \@desired_fields, $desired_table, $stipulations, $hash_or_not );
[..etc..]

@query_results  =  $db->select_all( \@desired_tables, $stipulations, $hash_or_not );

$db->select_incrementally( \@desired_fields, \@desired_tables, $stipulations );
$db->select_all_incrementally( \@desired_tables, $stipulations );

$next_row_ref  =  $db->get_next_row( $hash_or_not );

$number_of_rows  =  $db->count( $desired_table, $stipulations );

$a_single_value  =  $db->select_one_value( $desired_field, $desired_table, $stipulations );

@scalar_query_results  =  $db->select_one_column( $desired_field, \@desired_tables, $stipulations );

$single_row_ref  =  $db->select_one_row( \@desired_fields, \@desired_tables, $stipulations, $hash_or_not );

$db->delete( $desired_table, $stipulations );
$db->delete_all( $desired_table );

$db->insert( $desired_table, \%new_data );
$insert_id  =  $db->insert( $desired_table, \%new_data );  # MySQL only!!
$db->update( $desired_table, \%new_data, $stipulations );

$db->use_db( "another_database" );

$db->execute_sql( $some_raw_sql );

%table_schema  =  $db->get_table_schema( $table );

$primary_key   =  $db->get_primary_key( $table );

@auto_increment_fields  =  $db->get_auto_increments( $table );

#  Oracle users may find this one handy..
$db->force_lowercase_fields( );

#  this is just a wrapper around the corresponding DBI function
$db->func( @func_arguments, $func_name );

$db->disconnect( );

$db->finish( );

DESCRIPTION

DBIx::Broker does what it says, it breaks databases (using DBI!).
Or else you can use it to unclutter your code of its annoying
and ugly ->execute()s and ->prepare()s and the like.  It will 
work using any Perl DBI driver (via ->new()) or database handle
(via ->set_db_handle()).  The most common usage is to store the
query results in an array of references, each corresponding to
a row of results.  You may retrieve the results as array refs or
hash refs, depending upon whether you supplied 0 or 1,
respectively, as the $hash_or_not parameter.  For almost all
operations, you are able to supply the desired fields and
relevant tables either as a scalar (if there is just one value)
or as an array reference. i.e., you can say

$db->select( 'login', 'mail_accounts', 'WHERE status > 0', 1 )

or else set up something more complicated with field and table
arrays, like

@desired_fields  =  ( "c.firstName", "c.lastName", "c.customerID", "m.login" );
@desired_tables  =  ( "customers c", "mail_accounts m" );
$stipulations    =  'WHERE m.status > 0 AND m.assoc_customerID = c.customerID';
@query_results   =  $db->select( \@desired_fields, \@desired_tables, $stipulations, 1 );


For inserting and updating rows, you send a hashref whose keys are
the table field names and whose values are the new entries.  You may
also retrieve the insert ID for a new row upon $db->insert(); however,
this feature is currently only available with MySQL databases.

The *_incrementally() routines retrieve the same results as their
counterparts, but rather than returning all rows at once in an
array, the statement handle is left hanging and rows may be
retrieved one at a time, like

$next_row_ref  =  $db->get_next_row( $hash_or_not ).

It is recommended that you almost always use C<$hash_or_not = 1>,
for calling-level code readability, as well as extensibility.
Array references are supported only to avoid the inevitable
complaints that they are not supported.

The most common usage of $db->debug_on( ) is to send it \*STDERR
or \*STDOUT, but you can always have some fun and use a file
handle or a named pipe or something.  While debugging is on, all
SQL statements are printed to the debugging output handle for
examination.  This can be very handy.

Most of the time you\'ll be using this module something like

@customers  =  $db->select_all( 'customers', "WHERE age < 30", 1 );
foreach my $customer ( @customers ) {
    print "Customer $customer->{'customerID'}: ";
    print "$customer->{'last_name'}, $customer->{'first_name'}";
}


And if none of the existing functions are adequate, you can send
a raw SQL statement if you\'d like, by using

$db->execute_sql( "SELCET name FORM mailbox_tabel WHEER login = 'binkler'" );

You may retrieve table schema information in the form of a
hashtable, whose keys are the field names and whose values are
hashrefs to the various characteristics of each field, such as
'Type', 'Key', etc.  For convenience, the ->get_primary_key()
and ->get_auto_increments() methods have also been added.

AUTHOR

xomina@bitstream.net

SEE ALSO

perl(1), DBI(3).