DBIx::Handler - fork-safe and easy transaction handling DBI handler


  use DBIx::Handler;
  my $handler = DBIx::Handler->new($dsn, $user, $pass, $dbi_opts, $opts);
  my $dbh = $handler->dbh;


DBIx::Handler is fork-safe and easy transaction handling DBI handler.

DBIx::Handler provide scope base transaction, fork safe dbh handling, simple.


my $handler = DBIx::Handler->new($dsn, $user, $pass, $dbi_opts, $opts);

get database handling instance.


on_connect_do : CodeRef|ArrayRef[Str]|Str
on_disconnect_do : CodeRef|ArrayRef[Str]|Str

Execute SQL or CodeRef when connected/disconnected.

result_class : ClassName

This is a query method's result class. If this value is defined, $result_class-new($handler, $sth)> is called in query() and query() returns the instance.

trace_query : Bool

Enables to inject a caller information as SQL comment.

trace_ignore_if : CodeRef

Ignore to inject the SQL comment when trace_ignore_if's return value is true.

no_ping : Bool

By default, ping before each executing query. If it affect performance then you can set to true for ping stopping.

dbi_class : ClassName

By default, this module uses generally DBI class. For example, if you want to use another custom class compatibility with DBI, you can use it with this option.

prepare_method : Str

By default, this module uses generally prepare method. For example, if you want to use prepare_cached method or other custom method compatibility with prepare method, you can use it with this option.

my $handler = DBIx::Handler->connect($dsn, $user, $pass, $opts);

connect method is alias for new method.

my $dbh = $handler->dbh;

get fork safe DBI handle.


disconnect current database handle.

my $txn_guard = $handler->txn_scope

Creates a new transaction scope guard object.

    do {
        my $txn_guard = $handler->txn_scope;
            # some process

If an exception occurs, or the guard object otherwise leaves the scope before $txn->commit is called, the transaction will be rolled back by an explicit "txn_rollback" call. In essence this is akin to using a "txn_begin"/"txn_commit" pair, without having to worry about calling "txn_rollback" at the right places. Note that since there is no defined code closure, there will be no retries and other magic upon database disconnection.

$txn_manager = $handler->txn_manager

Get the DBIx::TransactionManager instance.


start new transaction.


commit transaction.


rollback transaction.


are you in transaction?

my @result = $handler->txn($coderef);

execute $coderef in auto transaction scope.

begin transaction before $coderef execute, do $coderef with database handle, after commit or rollback transaction.

  $handler->txn(sub {
      my $dbh = shift;

equals to:

      my $dbh = $handler->dbh;
my @result = $handler->run($coderef);

execute $coderef.

  my $rs = $handler->run(sub {
      my $dbh = shift;


  my @result = $handler->run(sub {
      my $dbh = shift;
my $sth = $handler->query($sql, [\@bind | \%bind]);

execute query. return database statement handler.

my $sql = $handler->trace_query_set_comment($sql);

inject a caller information as a SQL comment to $sql when trace_query is true.


The setters and the getters for options.



Atsushi Kobayashi <nekokak _at_ gmail _dot_ com>


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