view release on metacpan or  search on metacpan

Roles.pm  view on Meta::CPAN

C<< DBI-> connect >> outside the package are not affected, moreover, different
packages can import C<DBIx::Roles> with different roles.

The more generic syntax can be used to explicitly list the required roles:

   use DBIx::Roles;
   my $dbh = DBIx::Roles->new( qw(AutoReconnect SQLAbstract));
   $dbh-> connect( $dsn, $user, $pass);

or even

   use DBIx::Roles;
   my $dbh = DBIx::Roles-> connect( 
   	[qw(AutoReconnect SQLAbstract)], 
	$dsn, $user, $pass
   );

All these are equivalent, and result in construction of an object that plays
roles C<DBIx::Roles::AutoReconnect> and C<DBIx::Roles::SQLAbstract>, plus does all 
DBI functionality.

An example below uses C<DBIx::Roles> to contact a PostgreSQL DB, and then read 
some backend information:

   use strict;
   use DBIx::Roles qw(SQLAbstract StoredProcedures);
   
   # connect to a predefined DB template1
   my $d = DBI-> connect( 'dbi:Pg:dbname=template1', 'pgsql', '');
   
   # StoredProcedures converts pg_backend_pid() into "SELECT * FROM pg_backend_pid()"
   print "Backend PID: ", $d-> pg_backend_pid, "\n";
   
   # SQLAbstract declares select(), use it to read currently connected clients
   use Data::Dumper;
   my $st = $d-> select( 'pg_stat_activity', '*');
   print Dumper( $st-> fetchall_arrayref );
   
   # done
   $d-> disconnect;

The roles used in the example are basically syntactic sugar, but there are other roles
that do alter the program behavior, if applied. For example, adding C<AutoReconnect> to 
the list of the imported roles makes C<select()> calls restartable.

=head1 Predefined role modules

All modules included in packages have their own manual pages, so only brief
descriptions are provided here:

L<DBIx::Roles::AutoReconnect> - Restarts DB call if database connection breaks.
Based on idea of L<DBIx::AutoReconnect>

L<DBIx::Roles::Buffered> - Buffers write-only queries. Useful with lots of INSERTs
and UPDATEs over slow remote connections.

C<DBIx::Roles::Default> - not a module on its own, but a package that is
always imported, and need not to be imported explicitly. Implements actual calls
to DBI handle.

L<DBIx::Roles::Hook> - Exports callbacks to override DBI calls.

L<DBIx::Roles::InlineArray> - Flattens arrays passed as parameters to DBI calls into strings.

L<DBIx::Roles::RaiseError> - Change defaults to C<< RaiseError => 1 >>

L<DBIx::Roles::Shared> - Share DB connection handles. To be used instead of C<< DBI-> connect_cached >>.

L<DBIx::Roles::SQLAbstract> - Exports methods C<insert>,C<select>,C<update> etc in the
L<SQL::Abstract> fashion. Inspired by L<DBIx::Abstract>.

L<DBIx::Roles::StoredProcedures> - Treats any method reached AUTOLOAD as a call to a 
stored procedure.

L<DBIx::Roles::Transaction> - Allow nested transactions like C<DBIx::Transaction> does.

=head1 Programming interfaces

The interface that faces the caller is not fixed. Depending on the
functionality provided by roles, the methods can be added, deleted, or
completely changed. For example, the mentioned before hack that would want to
connect to a database using a DSN being read from a config file, wouldn't need
the first three parameters to C<connect> to be present, and rather would modify
the C<connect> call so that instead of

   connect( $dsn, $user, $pass, [$attr])

it might look like

   connect( [$attr])

Using this fictional module, I'll try to illustrate to how a DBI interface
can be changed.

=head2 Writing a new role

To be accessible, a new role must reside in a unique module ( and usually a
unique package). The C<DBIx::Roles> prefix is not required, but is a
convenience hack, and is added by default if the imported role name does not
contain colons. So, if the role is to be imported as 

    use DBIx::Roles qw(Config);

then it must be declared as

    package DBIx::Roles::Config;

=head2 Modifying parameters passed to DBI methods

To modify the parameters passed the role must define C<rewrite> method to
transform the parameters:

    sub rewrite
    {
        my ( $self, $storage, $method, $parameters) = @_;
	if ( $method eq 'connect') {
	     my ( $dsn, $user, $pass) = read_from_config;
	     unshift @$parameters, $dsn, $user, $pass;
	}
	return $self-> super( $method, $parameters);
    }