If there are no transactions currently running, "begin_work" will check if "AutoCommit" is enabled. If it is enabled, a "begin_work" instruction is sent to the underlying database layer. If "AutoCommit" is disabled, we assume that the database has already started a transaction for us, and do nothing. This means that you must always use begin_work to start a transaction, even if "AutoCommit" is enabled!

If there is a transaction started, "begin_work" simply records that a nested transaction has started.

"begin_work" returns the result of the database's "begin_work" call if it makes one; otherwise it always returns true.

If there are no sub-transactions currently running, "rollback" will issue the "rollback" call to the underlying database layer.

If there are sub-transactions currently running, "rollback" notes that the nested transaction has been aborted.

If there is no transaction running at all, "rollback" will raise a fatal error.

If there are no sub-transactions currently running, "commit" checks if there have been any transaction errors. If there has been a transaction error, "commit" raises an exception. Otherwise, a "commit" call is issued to the underlying database layer.

If there is no transaction running at all, "commit" will raise a fatal error. This error will contain a full stack trace, and should also contain the file names and line numbers where any rollbacks or query failures happened.

This method is supplied to make it easier to create nested transactions out of many small transactions. Example:

  sub get_max_id {
    my $dbh = shift;
    # this will roll back if it can't get MAX(num)
    $dbh->transaction(sub {
      if(my($id) = $dbh->selectrow_array("SELECT MAX(num) FROM foo")) {
        return $id;
      } else {
        return;
      }
    });
  }
  
  sub do_something {
    my($dbh, $num) = @_;
    $dbh->transaction(sub {
      $dbh->do("UPDATE foo SET bar = bar + 1 WHERE num = $num");
    });
  }
  
  sub do_many_things {
    my $dbh = shift;
    # if any of these sub-transactions roll back, the whole thing will roll
    # back. Try repeating the transaction up to 5 times.
    $dbh->transaction(sub {
      if(
        do_something($dbh, 1) &&
        do_something($dbh, 2) &&
        (my $id = get_max_id($dbh))
      ) {
        return do_something($dbh, $id);
      } else {
        return;
      }
    }, 5);
  }
    

  $dbh->rollback while $dbh->transaction_level;
    

But I would suggest that you structure your code so that each transaction and sub-transaction bails out safely instead, as that's a lot easier to trace and debug with confidence.