view release on metacpan or  search on metacpan

lib/DBIO/Storage/DBI.pm  view on Meta::CPAN

an SQL statement (e.g. the connection did not get stale, server is still
answering, etc.) This method is used internally by L</dbh>.

=head2 dbh

Returns a C<$dbh> - a data base handle of class L<DBI>. The returned handle
is guaranteed to be healthy by implicitly calling L</connected>, and if
necessary performing a reconnection before returning. Keep in mind that this
is very B<expensive> on some database engines. Consider using L</dbh_do>
instead.

=head2 register_driver

=over 4

=item Arguments: $dbd_driver_name, $storage_class

=item Return value: none

=back

Registers a mapping from a DBI driver name (for example C<Pg>, C<mysql>,
C<SQLite>) to a DBIO storage class.

This is primarily used by external DBIO driver distributions, so
L<DBIO::Storage::DBI> can rebless itself into the correct storage subclass
during driver detection.

Example:

  __PACKAGE__->register_driver('Pg' => 'DBIO::PostgreSQL::Storage');

=head2 register_connector_driver

=over 4

=item Arguments: $sql_dbms_name, $storage_class

=item Return value: none

=back

Registers a mapping from C<SQL_DBMS_NAME> values (as reported by ODBC/ADO
connectors) to a DBIO storage class. This is used by connector-based
secondary driver detection in L</_determine_connector_driver>.

Example:

  __PACKAGE__->register_connector_driver(
    'Microsoft_SQL_Server' => 'DBIO::MSSQL::Storage::ODBC',
  );

=head2 connect_call_datetime_setup

A no-op stub method, provided so that one can always safely supply the
L<connection option|/DBIO specific connection attributes>

 on_connect_call => 'datetime_setup'

This way one does not need to know in advance whether the underlying
storage requires any sort of hand-holding when dealing with calendar
data.

=head2 connect_call_rebase_sqlmaker

This on-connect call takes as a single argument the name of a class to "rebase"
the SQLMaker inheritance hierarchy upon. For this to work properly the target
class B<MUST> inherit from L<DBIO::SQLMaker::ClassicExtensions> and
either L<SQL::Abstract> or L<SQL::Abstract::Classic> as shown below.

This infrastructure is provided to aid recent activity around experimental new
aproaches to SQL generation within DBIO. You can (and are encouraged to)
mix and match old and new within the same codebase as follows:

  package DBIO::Awesomer::SQLMaker;
  # you MUST inherit in this order to get the composition right
  # you are free to override-without-next::method any part you need
  use base qw(
    DBIO::SQLMaker::ClassicExtensions
    << OPTIONAL::AWESOME::Class::Implementing::ExtraRainbowSauce >>
    SQL::Abstract
  );
  << your new code goes here >>


  ... and then ...


  my $experimental_schema = $original_schema->connect(
    sub {
      $original_schema->storage->dbh
    },
    {
      # the nested arrayref is important, as per
      # https://metacpan.org/pod/DBIO::Storage::DBI#on_connect_call
      on_connect_call => [ [ rebase_sqlmaker => 'DBIO::Awesomer::SQLMaker' ] ],
    },
  );

=head2 redact_bind_value

Class-level accessor for a coderef that decides how each bind value appears
in the trace output. The coderef is invoked as

  $redactor->($column_name, $value)

where C<$column_name> is the column name attached to the bind slot by the
SQL generator (or C<undef> for binds that carry no column metadata, such as
positional placeholders in raw SQL passed to L</do_query>). The coderef
returns the value to interpolate into the trace string. The raw bind value
sent to the database is not modified - only its representation in the trace
sink is.

The default redactor is the identity function, which preserves the
historical plaintext trace behavior. Install a custom redactor to scrub
credential or PII columns, e.g.:

  DBIO::Storage::DBI->redact_bind_value(sub {
      my ($colname, $value) = @_;
      return $colname eq 'password' ? '***' : $value;
  });