view release on metacpan or  search on metacpan

lib/DBIx/Connector.pm  view on Meta::CPAN

              say STDERR 'Transaction rollback failed too: ', $_->rollback_error;
          } else {
              warn "Caught exception: $_";
          }
      };
  });

But most of the time, you should be fine with the stringified form of the
exception, which will look something like this:

    Transaction aborted: Savepoint aborted: No such table "bar" at foo.pl line 190.
    Savepoint rollback failed: Invalid savepoint name at foo.pl line 161.
    Transaction rollback failed: Invalid transaction identifier at fool.pl line 184.

This allows you to see you original SQL error, as well as the errors for the
savepoint rollback and transaction rollback failures.

=head1 INTERFACE

And now for the nitty-gritty.

=head2 Constructor

=head3 C<new>

  my $conn = DBIx::Connector->new($dsn, $username, $password, {
      RaiseError => 1,
      AutoCommit => 1,
  });

Constructs and returns a DBIx::Connector object. The supported arguments are
exactly the same as those supported by the L<DBI>. Default values for those
parameters vary from the DBI as follows:

=over

=item C<RaiseError>

Defaults to true if unspecified, and if C<HandleError> is unspecified. Use of
the C<RaiseError> attribute, or a C<HandleError> attribute that always throws
exceptions (such as that provided by L<Exception::Class::DBI>), is required
for the exception-handling functionality of L<C<run()>|/"run">,
L<C<txn()>|/"txn">, and L<C<svp()>|/"svp"> to work properly. Their explicit
use is therefor recommended if for proper error handling with these execution
methods.

=item C<AutoInactiveDestroy>

Added in L<DBI> 1.613. Defaults to true if unspecified. This is important for
safe disconnects across forking processes.

=back

In addition, explicitly setting C<AutoCommit> to true is strongly recommended
if you plan to use L<C<txn()>|/"txn"> or L<C<svp()>|/"svp">, as otherwise you
won't get the transactional scoping behavior of those two methods.

If you would like to execute custom logic each time a new connection to the
database is made you can pass a sub as the C<connected> key to the
C<Callbacks> parameter. See L<DBI/Callbacks> for usage and other available
callbacks.

Other attributes may be modified by individual drivers. See the documentation
for the drivers for details:

=over

=item L<DBIx::Connector::Driver::MSSQL>

=item L<DBIx::Connector::Driver::Oracle>

=item L<DBIx::Connector::Driver::Pg>

=item L<DBIx::Connector::Driver::SQLite>

=item L<DBIx::Connector::Driver::mysql>

=item L<DBIx::Connector::Driver::Firebird>

=back

=head2 Class Method

=head3 C<connect>

  my $dbh = DBIx::Connector->connect($dsn, $username, $password, \%attr);

Syntactic sugar for:

  my $dbh = DBIx::Connector->new(@args)->dbh;

Though there's probably not much point in that, as you'll generally want to
hold on to the DBIx::Connector object. Otherwise you'd just use the L<DBI>,
no?

=head2 Instance Methods

=head3 C<dbh>

  my $dbh = $conn->dbh;

Returns the connection's database handle. It will use a an existing handle if
there is one, if the process has not been C<fork>ed or a new thread spawned,
and if the database is pingable. Otherwise, it will instantiate, cache, and
return a new handle.

When called from blocks passed to L<C<run()>|/"run">, L<C<txn()>|/"txn">, and
L<C<svp()>|/"svp">, C<dbh()> assumes that the pingability of the database is
handled by those methods and skips the C<ping()>. Otherwise, it performs all
the same validity checks. The upshot is that it's safe to call C<dbh()> inside
those blocks without the overhead of multiple C<ping>s. Indeed, it's
preferable to do so if you're doing lots of non-database processing in those
blocks.

=head3 C<run>

  $conn->run(ping => sub { $_->do($query) });

Simply executes the block, locally setting C<$_> to and passing in the
database handle. Returns the value returned by the block in scalar or array
context as appropriate (and the block can use C<wantarray> to decide what to