DBI connection and transaction management
Perl Perl6
Fetching latest commit…
Cannot retrieve the latest commit at this time.



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


use DBIx::Handler;
my $handler = DBIx::Handler->new($dsn, $user, $pass, $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, $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.

  • 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.

  • $handler->disconnect;

    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.

  • $handler->txn_begin

    start new transaction.

  • $handler->txn_commit

    commit transaction.

  • $handler->txn_rollback

    rollback transaction.

  • $handler->in_txn

    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.

  • result_class
  • trace_query
  • trace_ignore_if
  • no_ping
  • on_connect_do
  • on_disconnect_do


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.