view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    different packages can import "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 "DBIx::Roles::AutoReconnect" and "DBIx::Roles::SQLAbstract",
    plus does all DBI functionality.

    An example below uses "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 "AutoReconnect" to the list of the imported roles makes
    "select()" calls restartable.

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

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

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

    "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.

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

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

    DBIx::Roles::RaiseError - Change defaults to "RaiseError => 1"

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

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

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

    DBIx::Roles::Transaction - Allow nested transactions like
    "DBIx::Transaction" does.

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 "connect" to be present, and
    rather would modify the "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.

  Writing a new role
    To be accessible, a new role must reside in a unique module ( and
    usually a unique package). The "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;

  Modifying parameters passed to DBI methods
    To modify the parameters passed the role must define "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);
        }