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);
  $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 only the Pg, mSQL and mysql 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);

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.

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.

METHODS

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);

Updates any row of table which fulfill the conditions by inserting the given column/value pairs. Returns the number of rows modified.

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', 'id', 'price');
    $dbi_interface -> makemap ('components', 'id', 'price', '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.

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.

AUTHORS

Stefan Hornburg, racke@linuxia.de Dennis Schön, dennis@cobolt.net

SEE ALSO

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

cpanm DBIx::Easy

perl -MCPAN -e shell
install DBIx::Easy