Guillaume Aubert > DBIx-ScopedTransaction-1.1.0 > DBIx::ScopedTransaction

Download:
DBIx-ScopedTransaction-1.1.0.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: v1.1.0   Source   Latest Release: DBIx-ScopedTransaction-v1.1.5

NAME ^

DBIx::ScopedTransaction - Scope database transactions on DBI handles in code, to detect and prevent issues with unterminated transactions.

VERSION ^

Version 1.1.0

SYNOPSIS ^

        use DBIx::ScopedTransaction;
        use Try::Tiny;
        
        # Optional, define custom logger for errors detected when destroying a
        # transaction object. By default, this prints to STDERR.
        $DBIx::ScopedTransaction::DESTROY_LOGGER = sub
        {
                my ( $messages ) = @_;
                
                foreach my $message ( @$messages )
                {
                        warn "DBIx::ScopedTransaction: $message";
                }
        };
        
        # Start a transaction on $dbh - this in turn calls $dbh->begin_work();
        my $transaction = DBIx::ScopedTransaction->new( $dbh );
        try
        {
                # Do some work on $dbh that may succeed or fail.
        }
        finally
        {
                my @errors = @_;
                if ( scalar( @errors ) == 0 )
                {
                        $transaction->commit() || die 'Failed to commit transaction';
                }
                else
                {
                        $transaction->rollback() || die 'Failed to roll back transaction.';
                }
        };

DESCRIPTION ^

Small class designed to be instantiated in a localized scope. Its purpose is to start and then clean up a transaction on a DBI object, while detecting cases where the transaction isn't terminated properly.

The synopsis has an example of working code, let's see here an example in which DBIx::ScopedTransaction helps us to detect a logic error in how the programmer handled terminating the transaction.

        sub test
        {
                my $transaction = DBIx::ScopedTransaction->new( $dbh );
                try
                {
                        # Do some work on $dbh that may succeed or fail.
                }
                catch
                {
                        $transaction->rollback();
                };
        }
        
        test();

As soon as the test() function has been run, $transaction goes out of scope and gets destroyed by Perl. DBIx::ScopedTransaction subclasses destroy and detects that the underlying transaction has neither been committed nor rolled back, and forces a rollback for safety as well as prints details on what code should be reviewed on STDERR.

METHODS ^

new()

Create a new transaction.

        my $transaction = DBIx::ScopedTransaction->new(
                $database_handle,
        );

get_database_handle()

Return the database handle the current transaction is operating on.

        my $database_handle = $transaction->get_database_handle();

is_active()

Return whether the current transaction object is active.

        # Get the active status of the transaction.
        my $is_active = $transaction->is_active();

        # Set the active status of the transaction.
        $transaction->is_active( $is_active );

The transaction object goes inactive after a successful commit or rollback.

commit()

Commit the current transaction.

        my $commit_successful = $transaction->commit();

rollback()

Roll back the current transaction.

        my $rollback_successful = $transaction->rollback();

HIDDEN FUNCTIONS ^

_default_destroy_logger()

Log to STDERR warnings and errors that occur when a DBIx::ScopedTransaction object is destroyed.

        _default_destroy_logger( $messages );

To override this default logger you can override $DBIx::ScopedTransaction::DESTROY_LOGGER. For example:

        $DBIx::ScopedTransaction::DESTROY_LOGGER = sub
        {
                my ( $messages ) = @_;
                
                foreach $message ( @$messages )
                {
                        warn "DBIx::ScopedTransaction: $message";
                }
        };

DESTROY()

Clean up function to detect unterminated transactions and try to roll them back safely before destroying the DBIx::ScopedTransaction object.

AUTHOR ^

Guillaume Aubert, <aubertg at cpan.org>.

BUGS ^

Please report any bugs or feature requests to bug-dbix-scopedtransaction at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DBIx::ScopedTransaction. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT ^

You can find documentation for this module with the perldoc command.

        perldoc DBIx::ScopedTransaction

You can also look for information at:

ACKNOWLEDGEMENTS ^

Thanks to ThinkGeek (http://www.thinkgeek.com/) and its corporate overlords at Geeknet (http://www.geek.net/), for footing the bill while I write code for them!

COPYRIGHT & LICENSE ^

Copyright 2012 Guillaume Aubert.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

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 GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/

syntax highlighting: