NAME

DBIx::Wrap - Object oriented wrapper around DBI.

SYNOPSIS

use DBIx::Wrap;

my $dsn = "DBI:mysql:database=accounts";
$db = DBIx::Wrap->new (DSN => $dsn, User => 'jowaxman',
                       Password => 'plipplop');

# select
# Return a hash reference.
$user = $db->select (Table    => 'passwd',
                     Fields   => 'gcos,homedir,shell',
                     Where    => "username='jowaxman'");
$gcos = $user->{gcos};

# Set the table.
$db->table ('employees');

# Return an array of values.
@info = $db->select (Fields	=> 'ssn,address,phone',
                     Where    => "ssn='123456789'");
$ssn = $info[1];

# iterate
my $id;
while (my ($username, $gcos) = $db->each (\$id,
  Tables      => 'passwd,employees',
  Fields      => 'passwd.username,address,phone',
  Where       => "passwd.username=employees.username and
                  employees.status='fulltime'")) {
  # Note, could have done
  #   while (my $employee = $db->each (...
  # to get a hash.
}

# insert
$db->insert (Table    => 'passwd',
             Values   => {username	=> $username,
                          uid		=> $uid,
                          gcos	=> $gcos,
                          ...});

# delete
$db->delete (Table    => 'passwd',
             Where    => "username='jowaxman'");

DESCRIPTION

This module is a wrapper around the DBI database class. It simplifies database querying. You may use this as a base class for a derived class that operates on a specific kind of database.

CONSTRUCTOR

You must give the constructor the named parameters DSN, User, and Password so DBI can connect to the database.

ERROR HANDLING

DBIx::Wrap provides the public method error to do simple error handling. If an argument is given (the error), it is stored, otherwise, the stored error is returned.

error may be called as a package method (e.g., DBIx::Wrap->error ($error); or as an object method (e.g., $db->error ($error);. If it is called as a package method, the error is stored as a package variable. If it is called as an object method, the error is stored as a private variable.

PRIVATE METHODS

_prepare_sql

my $sql = $self->_prepare_sql ('select', \%params);

This private method prepares an sql statement given a set of named parameters. See the DBI or SQL documentation for more information on valid SQL phrases. The following named parameters are used:

Table or Tables

Specified the database table or tables. You can fix the table by using the method table (see below).

Field or Fields

Single field name or comma separated list of field names.

Where

A valid SQL WHERE clause.

Values

An anonymous hash containing column name/value pairs.

OrderBy

The ordering criteria.

Limit

A constraint limiting the number of rows returned.

PUBLIC METHODS

table

$self->table ('passwd');

This method fixes the table so that you do not have to specify the named parameter Table in any database method. This is very useful for repeated operations on the same table or when deriving a class that operates only on one table (see DB::passwd, for example).

select

$user = $db->select (Table    => 'passwd',
                     Where    => "username='jowaxman'");
@info = $db->select (Table    => 'passwd',
                     Fields   => 'gcos,homedir,shell',
                     Where    => "uid=12345");

This method performs an SQL SELECT operation. See _prepare_sql for the named parameters that are used.

If returning to a scalar, a reference to a hash containing column name/value pairs is returned. If returning to an array, a list of values in the same order as the fields specified in the named parameter Fields is returned. If no named parameter Fields is given, all fields are returned.

Note that if multiple entries match the WHERE clause, only the first will be returned.

each

my $id;
while (my ($username, $gcos) = $db->each (\$id,
                                 Table        => 'passwd',
                                 Fields       => 'username,gcos',
                               )) {
  # Note, could have done 
  #   while (my $user = $db->each (...
  # to get a hash.
}

Note that this method is deprecated. Use the iterator method.

This method is used for iterating through multiple database entries. See _prepare_sql for the named parameters used.

You must pass as the first arguement a reference to a scalar to store an id for the iteration. This allows iterations to be nested without conflict.

iterator

my $iterator = $db->iterator (Table	=> 'passwd',
                              Fields	=> 'username,gcos,homedir',
                              Where	=> "homedir like '/home/j/%");
while (my ($username, $gcos, $homedir) = $iterator->next ()) {
  ...
}

This method returns an iterator object used to iterate over multiple rows returned by an SQL query. See _prepare_sql for the named parameters used.

The iterator method next is used to return the first or next row. If next is called in an array context, an array of column values for the specified fields is returned. If next is called in a scalar context, a reference to a hash containing the name/values of the requested columns is returned.

insert

$db->insert (Table    => 'passwd',
             Values   => {username	=> $username,
                          uid		=> $uid,
                          gcos	=> $gcos,
                          ...});

This method inserts a new entry into a database table. See _prepare_sql for the named parameters used.

update

$db->update (Table    => 'passwd',
             Values   => {username    => $new_username,
                          pwd         => 'x',
                          uid         => $uid,
                          ...},
             Where    => "username='$old_username'");

This method updates an existing entry in a database table. See _prepare_sql for the named parameters used.

delete

$db->delete (Table    => 'users',
             Where    => "username='jowaxman'");

This method deletes an existing entry from a database table. See _prepare_sql for the named parameters used.

show_tables

my @tables = $db->show_tables ();

This method returns an array containg the table names.

describe

my $table_info = $db->describe (Table => 'users');

This method returns a reference to a hash containing information about fields.

AUTHOR

Jonathan Waxman jowaxman@law.upenn.edu

COPYRIGHT

Copyright (c) 2002 Jonathan A. Waxman All rights reserved.

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

cpanm DBIx::Wrap

perl -MCPAN -e shell
install DBIx::Wrap