/ 
DBIx-ScopedTransaction-v1.2.0
River stage zero No dependents
/ DBIx::ScopedTransaction

NAME

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

VERSION

Version 1.2.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.

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/guillaumeaubert/DBIx-ScopedTransaction/issues/new. 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:

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

ACKNOWLEDGEMENTS

I originally developed this project for ThinkGeek (http://www.thinkgeek.com/). Thanks for allowing me to open-source it!

COPYRIGHT & LICENSE

Copyright 2012-2017 Guillaume Aubert.

This code is free software; you can redistribute it and/or modify it under the same terms as Perl 5 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 LICENSE file for more details.