The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
DBIx-LazyMethod-1.03
River stage zero No dependents
++
/ DBIx::LazyMethod

NAME

DBIx::LazyMethod - Simple 'database query-to-accessor method' wrappers. Quick and dirty OO interface to your data.

SYNOPSIS

When used directly:

  use DBIx::LazyMethod;

  my %methods = (
        set_people_name_by_id => {
                sql => "UPDATE people SET name = ? WHERE id = ?",
                args => [ qw(name id) ],
                ret => WANT_RETURN_VALUE,
        },
        get_people_entry_by_id => {
                sql => "SELECT * FROM people WHERE id = ?",
                args => [ qw(id) ],
                ret => WANT_HASHREF,
        },
        # Although not really recommended, you can also change table data
        drop_table => {
                sql => "DROP TABLE ?",
                args => [ qw(table) ],
                ret => WANT_RETURN_VALUE,
                noprepare => 1, # For non-prepareable queries
                noquote => 1,   # For non-quoteable arguments (like table names)
        },
  );

  #set up the above methods on a Oracle database accessible through a DBI proxy 
  my $db = DBIx::LazyMethod->new(
                data_source  => "DBI:Proxy:hostname=192.168.1.1;port=7015;dsn=DBI:Oracle:PERSONS",
                user => 'user',
                pass => 'pass',
                attr => { 'RaiseError' => 0, 'AutoCommit' => 1 },
                methods => \%methods,  
                );
  if ($db->is_error) { die $db->{errormessage}; }

 Accessor methods are now available:
 
  my $rv = $db->set_people_name_by_id(name=>'Arne Raket', id=>42);
  if ($db->is_error) { die $db->{errormessage}; }

  my $rv2 = $db->drop_table(table=>'pony');
  if ($db->is_error) { die $db->{errormessage}; }

When sub-classed:

  use MyDB;     # Class inheriting everything from DBIx::LazyMethod except for 
                # the C<new> method - which is just a call to DBIx::LazyMethod 
                # with appropriate arguments - returning a DBIx::LazyMethods 
                # object. See lib/SomeDB.pm for an example.

  my $db = MyDB->new() or die;
 
 Accessor methods are now available:

  my $entry_ref = $db->get_people_entry_by_id(id=>42);

DESCRIPTION

A Lazy (and easily replaceable) DB abstraction layer. In no way a new approach, rather an easy one. You should probably use DBIx::Class anyway. Heh.

What does that mean?

DBIx::LazyMethod uses AUTOLOAD to create methods and statement handles based on the data in the hashref supplied in the argument 'methods'. Statement handles are persistent in the lifetime of the instance. It is an easy way to set up accessor methods for a fixed (in the sense of database and table layout) data set.

When the DBIx::LazyMethod object is created, it is verified, for each method in the 'methods' hashref, that the amount of required arguments matches the amount of placeholders in the SQL ("?").

When a method defined in the 'methods' hashref is invoked, it is verified that the arguments in 'args' are provided. The arguments are then applied to the persistent statement handle (eg. _sth_set_people_name_by_id) that is created from the value 'sql' statement.

If the 'args' start with 'limit_' they are handled specially to enable placeholders for 'LIMIT X,Y' (MySQL) syntax - if mysql DBD is used.

Why did you do that?

I was annoyed by the fact that I had to create virtually similar DB packages time and time again. DBIx::LazyMethod started out as an experiment in how generic a (simple) DB module could be made. In many situations you would probably want to create a specialized DB package - but this one should get you started, without you having to change your interfaces at a later point. Besides that. I'm just lazy.

KEYS IN METHODS DEFINITION

The 'args', 'sql' and 'ret' are mandatory arguments to each defined method.

The 'noprepare' and 'noquote' arguments are optional.

args

The value of 'args' is an array of key names. The keys must be in the same order as the mathing SQL placeholders ("?"). When the object is created, it is checked that the amount of keys match the amount of SQL placeholders.

sql

The 'sql' key holds the string value of the fixed SQL syntax.

ret

The value of 'ret' (return value) can be:

  • WANT_ARRAY returns in array context (SELECT)

  • WANT_ARRAYREF returns a reference to an array - or undef (SELECT)

  • WANT_HASHREF returns a reference to a hash - or undef (SELECT)

  • WANT_ARRAY_HASHREF returns an array of hashrefs (SELECT)

  • WANT_RETURN_VALUE returns the DBI returnvalue (NON-SELECT)

  • WANT_AUTO_INCREMENT returns the new auto_increment value of an INSERT (MySQL/Pg specific).

noprepare

The existence of the 'noprepare' key indicates that the method should not use a prepared statement handle for execution. This is really just slower. It should be used when executing queries that cannot be prepared. (Like 'DROP TABLE ?'). It only works with non-SELECT statements. So setting 'ret' to anything else than WANT_RETURN_VALUE will cause an error. See the 'bind_param' section of the 'Statement Handle Methods' in the DBI documentation for more information.

noquote

The existence of the 'noquote' key indicates that the arguments listed should not be quoted. This is for dealing with table names (Like 'DROP TABLE ?'). It's really a hack. The 'noquote' key has no effect unless used in collaboration with the 'noprepare' key on a method.

CLASS METHODS

The following methods are available from DBIx::LazyMethod objects. Any function or method not documented should be considered private. If you call it, your code may break someday and it will be your fault.

The methods follow the Perl tradition of returning false values when an error occurs (and usually setting $@ with a descriptive error message).

Any method which takes an SQL query string can also be passed bind values for any placeholders in the query string:

new()

The new() constructor creates and returns a database connection object through which all database actions are conducted. On error, it will call die(), so you may want to eval {...} the call. The NoAbort option (described below) controls that behavior.

new() accepts ``hash-style'' key/value pairs as arguments. The arguments which it recognizes are:

data_source

The data source normally fed to DBI->connect. Normally in the format of dbi:DriverName:database_name.

user

The database connection username.

pass

The database connection password.

attr

The database connection attributes. Leave blank for DBI defaults.

methods

The methods hash reference. Also see the KEYS IN METHODS DEFINITION description.

noprepare (optional)

If defined - causes the method to be executed directly, without involving a statement handle.

noquote (optional)

When defined, the arguments will not be quoted/escaped before execution. This is normally only used for table names. noprepare must also be defined for this option to work.

is_error()

The is_error() simply returns true if the internal error state flag has been set. The errormessage is then available from $db->{errormessage}; .

COPYRIGHT

Copyright (c) 2002-04 Casper Warming <cwg@usr.bin.dk>. All rights reserved.

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Artistic License for more details.

AUTHOR

Casper Warming <cwg@usr.bin.dk>

TODO

More DBD specific functions (Oracle/Pg).
Better documentation.
More "failure" tests.
Testing expired statement handles.

ACKNOWLEDGEMENTS

Copenhagen Perl Mongers for the motivation.
Sorry to Thomas Eibner for not naming the module Doven::Hest.
JONASBN for reporting errors and helping with Pg issues.

SEE ALSO

DBIx::DWIW

DBIx::Class

Class::Accessor

DBI(1).