DBIx::ScopedTransaction - Scope database transactions on DBI handles in code, to detect and prevent issues with unterminated transactions.
Version 1.0.3
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.'; } };
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.
Creates a new transaction.
my $transaction = DBIx::ScopedTransaction->new( $database_handle, );
Returns the database handle the current transaction is operating on.
my $database_handle = get_database_handle();
Returns whether the current transaction object is active.
my $boolean = $self->is_active(); my $boolean = $self->is_active( $boolean );
Commits the current transaction.
my $boolean = $self->commit();
Rolls back the current transaction.
my $boolean = $self->rollback();
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
$DBIx::ScopedTransaction::DESTROY_LOGGER = sub { my ( $messages ) = @_; foreach $message ( @$messages ) { warn "DBIx::ScopedTransaction: $message"; } };
Clean up function to detect unterminated transactions and try to roll them back safely before destroying the DBIx::ScopedTransaction object.
Guillaume Aubert, <aubertg at cpan.org>.
<aubertg at cpan.org>
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.
bug-dbix-scopedtransaction at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc DBIx::ScopedTransaction
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx::ScopedTransaction
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/DBIx::ScopedTransaction
CPAN Ratings
http://cpanratings.perl.org/d/DBIx::ScopedTransaction
Search CPAN
http://search.cpan.org/dist/DBIx::ScopedTransaction/
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 2012 Guillaume Aubert.
This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install DBIx::ScopedTransaction, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBIx::ScopedTransaction
CPAN shell
perl -MCPAN -e shell install DBIx::ScopedTransaction
For more information on module installation, please visit the detailed CPAN module installation guide.