NAME
    DBIx::Wrapper - A wrapper around the DBI

SYNOPSIS
     use DBIx::Wrapper;

     my $db = DBIx::Wrapper->connect($dsn, $user, $auth, \%attr);

     my $dbi_obj = DBI->connect(...)
     my $db = DBIx::Wrapper->newFromDBI($dbi_obj);

     my $dbi_obj = $db->getDBI;

     my $rv = $db->insert($table, { id => 5, val => "myval",
                                    the_date => \"NOW()"
                                  });
     my $rv = $db->replace($table, \%data);
     my $rv = $db->delete($table, \%keys);
     my $rv = $db->update($table, \%keys, \%data);
     my $rv = $db->smartUpdate($table, \%keys, \%data);

     my $row = $db->selectFromHash($table, \%keys);
     my $row = $db->nativeSelect($query, \@exec_args);

     my $loop = $db->nativeSelectExecLoop($query);
     foreach my $val (@vals) {
         my $row = $loop->next([ $val ]);
     }

     my $row = $db->nativeSelectWithArrayRef($query, \@exec_args);

     my $rows = $db->nativeSelectMulti($query, \@exec_args);

     my $loop = $db->nativeSelectMultiExecLoop($query)
     foreach my $val (@vals) {
         my $rows = $loop->next([ $val ]);
     }

     my $rows = $db->nativeSelectMultiWithArrayRef($query, \@exec_args);

     my $hash = $db->nativeSelectMapping($query, \@exec_args);
     my $hash = $db->nativeSelectDynaMapping($query, \@cols, \@exec_args);

     my $hash = $db->nativeSelectRecordMapping($query, \@exec_args);
     my $hash = $db->nativeSelectRecordDynaMapping($query, $col, \@exec_args);

     my $val = $db->nativeSelectValue($query, \@exec_args);

     my $row = $db->abstractSelect($table, \@fields, \%where, \@order);
     my $rows = $db->abstractSelectMulti($table, \@fields, \%where, \@order);

     my $loop = $db->nativeSelectLoop($query, @exec_args);

     my $rv = $db->nativeQuery($query, @exec_args);

     my $loop = $db->nativeQueryLoop("UPDATE my_table SET value=? WHERE id=?");
     $loop->next([ 'one', 1]);
     $loop->next([ 'two', 2]);

     my $id = $db->getLastInsertId;

     $db->debugOn(\*FILE_HANDLE);

     $db->setNameArg($arg)

     $db->commit();
     $db->ping();
     $db->err();

DESCRIPTION
    DBIx::Wrapper provides a wrapper around the DBI that makes it a bit
    easier on the programmer. This module allows you to execute a query with
    a single method call.

METHODS
  connect($data_source, $username, $auth, \%attr)
    Connects to the given database. These are the same parameters you would
    pass to the connect call when using DBI directly.

  new($data_source, $username, $auth, \%attr)
    An alias for connect().

  newFromDBI($dbh)
    Returns a new DBIx::Wrapper object from a DBI object that has already
    been created. Note that when created this way, disconnect() will not be
    called automatically on the underlying DBI object when the DBIx::Wrapper
    object goes out of scope.

  getDBI()
    Return the underlying DBI object used to query the database.

  insert($table, \%data)
    Insert the provided row into the database. $table is the name of the
    table you want to insert into. %data is the data you want to insert -- a
    hash with key/value pairs representing a row to be insert into the
    database.

  replace($table, \%data)
    Same as insert(), except does a REPLACE instead of an INSERT for
    databases which support it.

  smartReplace($table, \%data)
     This method is MySQL specific.  If $table has an auto_increment
     column, the return value will be the value of the auto_increment
     column.  So if that column was specified in \%data, that value
     will be returned, otherwise, an insert will be performed and the
     value of LAST_INSERT_ID() will be returned.  If there is no
     auto_increment column, but primary keys are provided, the row
     containing the primary keys will be returned.  Otherwise, a true
     value will be returned upon success.

  delete($table, \%keys), delete($table, \@keys)
     Delete rows from table $table using the key/value pairs in %keys
     to specify the WHERE clause of the query.  Multiple key/value
     pairs are joined with 'AND' in the WHERE clause.  The cols
     parameter can optionally be an array ref instead of a hashref.
     E.g.

         $db->delete($table, [ key1 => $val1, key2 => $val2 ])

     This is so that the order of the parameters in the WHERE clause
     are kept in the same order.  This is required to use the correct
     multi field indexes in some databases.

  update($table, \%keys, \%data), update($table, \@keys, \%data)
     Update the table using the key/value pairs in %keys to specify
     the WHERE clause of the query.  %data contains the new values
     for the row(s) in the database.  The keys parameter can
     optionally be an array ref instead of a hashref.  E.g.,

         $db->update($table, [ key1 => $val1, key2 => $val2 ], \%data);

     This is so that the order of the parameters in the WHERE clause
     are kept in the same order.  This is required to use the correct
     multi field indexes in some databases.

  selectFromHash($table, \%keys);
     Select from table $table using the key/value pairs in %keys to
     specify the WHERE clause of the query.  Multiple key/value pairs
     are joined with 'AND' in the WHERE clause.  Returns a single row
     as a hashref.

  smartUpdate($table, \%keys, \%data)
    Same as update(), except that a check is first made to see if there are
    any rows matching the data in %keys. If so, update() is called,
    otherwise, insert() is called.

  nativeSelect($query, \@exec_args)
    Executes the query in $query and returns a single row result (as a hash
    ref). If there are multiple rows in the result, the rest get silently
    dropped. @exec_args are the same arguments you would pass to an
    execute() called on a DBI object. Returns undef on error.

  nativeSelectExecLoop($query)
     Like nativeSelect(), but returns a loop object that can be used
     to execute the same query over and over with different bind
     parameters.  This does a single DBI prepare() instead of a new
     prepare() for select.

     E.g.,

         my $loop = $db->nativeSelectExecLoop("SELECT * FROM mytable WHERE id=?");
         foreach my $id (@ids) {
             my $row = $loop->next([ $id ]);
         }

  nativeSelectWithArrayRef($query, \@exec_args)
     Like nativeSelect(), but return a reference to an array instead
     of a hash.  Returns undef on error.  If there are no results
     from the query, a reference to an empty array is returned.

  nativeSelectMulti($query, \@exec_args)
     Executes the query in $query and returns an array of rows, where
     each row is a hash representing a row of the result.  Returns
     undef on error.  If there are no results for the query, an empty
     array ref is returned.

  nativeSelectMultiExecLoop($query)
     Like nativeSelectExecLoop(), but returns an array of rows, where
     each row is a hash representing a row of the result.

  nativeSelectMultiWithArrayRef($query, \@exec_args)
     Like nativeSelectMulti(), but return a reference to an array of
     arrays instead of to an array of hashes.  Returns undef on error.

  nativeSelectMapping($query, \@exec_args)
     Executes the given query and returns a reference to a hash
     containing the first and second columns of the results as
     key/value pairs.

  nativeSelectDynaMapping($query, \@cols, \@exec_args)
     Similar to nativeSelectMapping() except you specify which
     columns to use for the key/value pairs in the return hash.  If
     the first element of @cols starts with a digit, then @cols is
     assumed to contain indexes for the two columns you wish to use.
     Otherwise, @cols is assumed to contain the field names for the
     two columns you wish to use.

     For example,

         nativeSelectMapping($query, \@exec_args) is

      equivalent (and in fact calls) to

         nativeSelectDynaMapping($query, [ 0, 1 ], $exec_args).

  nativeSelectRecordMapping($query, \@exec_args)
     Similar to nativeSelectMapping(), except the values in the hash
     are references to the corresponding record (as a hash).

  nativeSelectRecordDynaMapping($query, $col, \@exec_args)
     Similar to nativeSelectRecordMapping(), except you specify
     which column is the key in each key/value pair in the hash.  If
     $col starts with a digit, then it is assumed to contain the
     index for the column you wish to use.  Otherwise, $col is
     assumed to contain the field name for the two columns you wish
     to use.

  nativeSelectValue($query, \@exec_args)
     Returns a single value, the first column from the first row of
     the result.  Returns undef on error or if there are no rows in
     the result.  Note this may be the same value returned for a NULL
     value in the result.

  abstractSelect($table, \@fields, \%where, \@order)
    Same as nativeSelect() except uses SQL::Abstract to generate the SQL.
    See the POD for SQL::Abstract for usage. You must have SQL::Abstract
    installed for this method to work.

  abstractSelectMulti($table, \@fields, \%where, \@order)
    Same as nativeSelectMulti() except uses SQL::Abstract to generate the
    SQL. See the POD for SQL::Abstract for usage. You must have
    SQL::Abstract installed for this method to work.

  nativeSelectLoop($query, @exec_args)
    Executes the query in $query, then returns an object that allows you to
    loop through one result at a time, e.g.,

        my $loop = $db->nativeSelectLoop("SELECT * FROM my_table");
        while (my $row = $loop->next) {
            my $id = $$row{id};
        }

        To get the number of rows selected, you can call the
        rowCountCurrent() method on the loop object, e.g.,

        my $loop = $db->nativeSelectLoop("SELECT * FROM my_table");
        my $rows_in_result = $loop->rowCountCurrent;

        The count() method is an alias for rowCountCurrent().

        To get the number of rows returned by next() so far, use the
        rowCountTotal() method.

  nativeQuery($query, @exec_args)
    Executes the query in $query and returns true if successful. This is
    typically used for deletes and is a catchall for anything the methods
    provided by this module don't take into account.

  nativeQueryLoop($query)
    A loop on nativeQuery, where any placeholders you have put in your query
    are bound each time you call next(). E.g.,

        my $loop = $db->nativeQueryLoop("UPDATE my_table SET value=? WHERE id=?");
        $loop->next([ 'one', 1]);
        $loop->next([ 'two', 2]);

  newCommand($cmd)
    This creates a literal SQL command for use in insert(), update(), and
    related methods, since if you simply put something like "CUR_DATE()" as
    a value in the %data parameter passed to insert, the function will get
    quoted, and so will not work as expected. Instead, do something like
    this:

        my $data = { file => 'my_document.txt',
                     the_date => $db->newCommand('CUR_DATE()')
                   };
        $db->insert('my_doc_table', $data);

    This can also be done by passing a reference to a string with the SQL
    command, e.g.,

        my $data = { file => 'my_document.txt',
                     the_date => \'CUR_DATE()'
                   };
        $db->insert('my_doc_table', $data);

  debugOn(\*FILE_HANDLE)
    Turns on debugging output. Debugging information will be printed to the
    given filehandle.

  debugOff()
    Turns off debugging output.

  setNameArg($arg)
    This is the argument to pass to the fetchrow_hashref() call on the
    underlying DBI object. By default, this is 'NAME_lc', so that all field
    names returned are all lowercase to provide for portable code. If you
    want to make all the field names return be uppercase, call
    $db->setNameArg('NAME_uc') after the connect() call. And if you really
    want the case of the field names to be what the underlying database
    driveer returns them as, call $db->setNameArg('NAME').

  err()
    Calls err() on the underlying DBI object, which returns the native
    database engine error code from the last driver method called.

  commit()
    Calls commit() on the underlying DBI object to commit your transactions.

  ping()
    Calls ping() on the underlying DBI object to see if the database
    connection is still up.

  getLastInsertId(), get_last_insert_id(), last_insert_id()
     Returns the last_insert_id.  This is MySQL specific for now.  It
     just runs the query "SELECT LAST_INSERT_ID()".

  There are also underscore_separated versions of these methods.
        E.g., nativeSelectLoop() becomes native_select_loop()

TODO
    More logging/debugging options
    Allow prepare() and execute() for easier integration into existing code.

ACKNOWLEDGEMENTS
        People who have contributed ideas and/or code for this module:

        Kevin Wilson
        Mark Stosberg

AUTHOR
        Don Owens <don@owensnet.com>

COPYRIGHT
        Copyright (c) 2003-2004 Don Owens

        All rights reserved. This program is free software; you can
        redistribute it and/or modify it under the same terms as Perl
        itself.

VERSION
        0.10