/ 
DBIO-0.900004
/ DBIO::Storage::TxnScopeGuard

NAME

DBIO::Storage::TxnScopeGuard - Scope-based transaction handling

VERSION

version 0.900004

SYNOPSIS

sub foo {
  my ($self, $schema) = @_;

  my $guard = $schema->txn_scope_guard;

  # Multiple database operations here

  $guard->commit;
}

See t/storage/txn_scope_guard.t for a runnable example: BEGIN on creation, COMMIT on ->commit, and the implicit ROLLBACK when a guard leaves scope without an explicit commit.

DESCRIPTION

An object that behaves much like Scope::Guard, but hardcoded to do the right thing with transactions in DBIO.

METHODS

new

Creating an instance of this class will start a new transaction (by implicitly calling "txn_begin" in DBIO::Storage. Expects a DBIO::Storage object as its only argument.

commit

Commit the transaction, and stop guarding the scope. If this method is not called and this object goes out of scope (e.g. an exception is thrown) then the transaction is rolled back, via "txn_rollback" in DBIO::Storage

If the commit itself fails, the guard is spent all the same and the commit's error is thrown: the storage has already reset its transaction state (depth 0), tried a rollback and, when that failed as well, discarded the handle (see "txn_commit" in DBIO::Storage). A following statement does not run inside the failed transaction.

rollback

Roll back the transaction, and stop guarding the scope. You can use this to avoid the warning when the scope guard goes out of scope, for deliberate rollbacks.

WHEN THE ROLLBACK FAILS

The rollback a guard issues on going out of scope can fail in turn, and then the transaction may still be open on the connection. Where that is reported depends on the exception in flight at that point, which to the guard is an exception in $@ that was not there when the guard was created:

  • Exactly a DBIO::Exception, not a subclass of it: its message becomes Transaction aborted: $message Rollback failed: $rollback_error. The caller catches the same object, and nothing is warned.

  • Any other exception - a string, an object of another class, a subclass of DBIO::Exception: the guard cannot write into it, so it warns ROLLBACK FAILED with the rollback error and the text of that exception. An exception that is unwinding the stack reaches the caller as it was thrown.

  • No exception: the guard warns ROLLBACK FAILED with the rollback error.

The DBIO::Storage::NESTED_ROLLBACK_EXCEPTION a rollback raises inside an enclosing transaction without savepoints (see "txn_rollback" in DBIO::Storage) is not a failure and is not reported: the enclosing transaction rolls back.

SEE ALSO

"txn_scope_guard" in DBIO::Schema.

Scope::Guard by chocolateboy (inspiration for this module)

AUTHOR

DBIO & DBIx::Class Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.