NAME

       DBIx::Easy - Easy to Use DBI interface

SYNOPSIS

         use DBIx::Easy;
         my $dbi_interface = new DBIx::Easy qw(Pg template1);

         $dbi_interface -> insert ('transaction',
                          id => serial ('transaction', 'transactionid'),
                          time => \$dbi_interface -> now);

         $dbi_interface -> update ('components', "table='ram'", price => 100);
         $rows_deleted = $dbi_interface -> delete ('components', 'stock = 0');
         $dbi_interface -> makemap ('components', 'id', 'price', 'price > 10');
         $components = $dbi_interface -> rows ('components');
         $components_needed = $dbi_interface -> rows ('components', 'stock = 0');

DESCRIPTION

       DBIx::Easy is an easy to use DBI interface.  Currently the Pg, mSQL, mysql, Sybase, ODBC
       and XBase drivers are supported.

CREATING A NEW DBI INTERFACE OBJECT

         $dbi_interface = new DBIx::Easy qw(Pg template1);
         $dbi_interface = new DBIx::Easy qw(Pg template1 racke);
         $dbi_interface = new DBIx::Easy qw(Pg template1 racke aF3xD4_i);
         $dbi_interface = new DBIx::Easy qw(Pg template1 racke@linuxia.de aF3xD4_i);
         $dbi_interface = new DBIx::Easy qw(Pg template1 racke@linuxia.de:3306 aF3xD4_i);

       The required parameters are the database driver and the database name. Additional
       parameters are the database user and the password to access the database. To specify the
       database host use the USER@HOST notation for the user parameter. If you want to specify
       the port to connect to use USER@HOST:PORT.

DESTROYING A DBI INTERFACE OBJECT

       It is important that you commit all changes at the end of the interaction with the DBMS.
       You can either explicitly commit

         $dbi_interface -> commit ();

       or do it implicitly:

         undef $dbi_interface;

ERROR HANDLING

         sub fatal {
           my ($statement, $err, $msg) = @_;
           die ("$0: Statement \"$statement\" failed (ERRNO: $err, ERRMSG: $msg)\n");
         }
         $dbi_interface -> install_handler (\&fatal);

       If any of the DBI methods fails, either die will be invoked or an error handler installed
       with install_handler will be called.

CACHING ISSUES

       By default, this module caches table structures. This can be disabled by setting
       $DBIx::Easy::cache_structs to 0.

XBASE DRIVER

       The DBIx::Easy method rows fails to work with the DBD::XBase driver.

METHODS

   DATABASE ACCESS
       process statement
             $sth = $dbi_interface -> process ("SELECT * FROM foo");
             print "Table foo contains ", $sth -> rows, " rows.\n";

           Processes statement by just combining the prepare and execute steps of the DBI.
           Returns statement handle in case of success.

       insert table column value [column value] ...
             $sth = $dbi_interface -> insert ('bar', drink => 'Caipirinha');

           Inserts the given column/value pairs into table. Determines from the SQL data type
           which values has to been quoted. Just pass a reference to the value to protect values
           with SQL functions from quoting.

       update table conditions column value [column value] ...
             $dbi_interface -> update ('components', "table='ram'", price => 100);
             $dbi_interface -> update ('components', "table='ram'", price => \"price + 20");

           Updates any row of table which fulfill the conditions by inserting the given
           column/value pairs. Scalar references can be used to embed strings without further
           quoting into the resulting SQL statement. Returns the number of rows modified.

       put table conditions column value [column value] ...
       delete table conditions
             $dbi_interface -> delete ('components', "stock=0");

           Deletes any row of table which fulfill the conditions. Without conditions all rows are
           deleted. Returns the number of rows deleted.

       do_without_transaction statement
             $sth = $dbi_interface -> do_without_transaction ("CREATE DATABASE foo");

             Issues a DBI do statement while forcing autocommit. This is used for
             statements that can't be run in transaction mode (like CREATE DATABASE
             in PostgreSQL).

       rows table [conditions]
             $components = $dbi_interface -> rows ('components');
             $components_needed = $dbi_interface -> rows ('components', 'stock = 0');

           Returns the number of rows within table satisfying conditions if any.

       makemap table keycol valcol [condition]
               $dbi_interface -> makemap ('components', 'idf', 'price');
               $dbi_interface -> makemap ('components', 'idf', 'price', 'price > 10');
               $dbi_interface -> makemap ('components', 'idf', '*');
               $dbi_interface -> makemap ('components', 'idf', '*', 'price > 10');

           Produces a mapping between the values within column keycol and column valcol from
           table. If an condition is given, only rows matching this condition are used for the
           mapping.

           In order to get the hash reference to the record as value of the mapping, use the
           asterisk as the valcol parameter.

       random_row table conditions [map]
           Returns random row of the specified table. If map is set, the result is a hash
           reference of the selected row, otherwise an array reference. If the table doesn't
           contains rows, undefined is returned.

       serial table sequence
           Returns a serial number for table by querying the next value from sequence. Depending
           on the DBMS one of the parameters is ignored.  This is sequence for mSQL resp. table
           for PostgreSQL. mysql doesn't support sequences, but the AUTO_INCREMENT keyword for
           fields.  In this case this method returns 0 and mysql generates a serial number for
           this field.

       fill sth hashref [flag column ...]
           Fetches the next table row from the result stored into sth and records the value of
           each field in hashref. If flag is set, only the fields specified by the column
           arguments are considered, otherwise the fields specified by the column arguments are
           omitted.

       view table [name value ...]
             foreach my $table (sort $dbi_interface -> tables)
               {
               print $cgi -> h2 ('Contents of ', $cgi -> code ($table));
               print $dbi_interface -> view ($table);
               }

           Produces plain text representation of the database table table. This method accepts
           the following options as name/value pairs:

           columns: Which columns to display.

           order: Which column to sort the row after.

           limit: Maximum number of rows to display.

           separator: Separator inserted between the columns.

           where: Display only rows matching this condition.

             print $dbi_interface -> view ($table,
                                           order => $cgi -> param ('order') || '',
                                           where => "price > 0");

   DATABASE INFORMATION
       is_table NAME
           Returns truth value if there exists a table NAME in this database.

       tables
           Returns list of all tables in this database.

       sequences
           Returns list of all sequences in this database (Postgres only).

       columns TABLE
           Returns list of the column names of TABLE.

       types TABLE
           Returns list of the column types of TABLE.

       sizes TABLE
           Returns list of the column sizes of TABLE.

       typemap TABLE
           Returns mapping between column names and column types for table TABLE.

       sizemap TABLE
           Returns mapping between column names and column sizes for table TABLE.

   TIME VALUES
       now
             $dbi_interface -> insert ('transaction',
                              id => serial ('transaction', 'transactionid'),
                              time => \$dbi_interface -> now);

           Returns representation for the current time. Uses special values of the DBMS if
           possible.

   MONETARY VALUES
       money2num money
           Converts the monetary value money to a numeric one.

   MISCELLANEOUS
       is_auth_error msg
           This method decides if the error message msg is caused by an authentification error or
           not.

AUTHORS

       Stefan Hornburg (Racke), racke@linuxia.de Dennis Sch\[:o]n, ds@1d10t.de

       Support for Sybase and ODBC provided by David B. Bitton <david@codenoevil.com>.

VERSION

       0.20

SEE ALSO

       perl(1), DBI(3), DBD::Pg(3), DBD::mysql(3), DBD::msql(3), DBD::Sybase(3), DBD::ODBC(3).