NAME

DBIWrap - Convenience Sub-Class of DBI

VERSION

version 1.6.0

SYNOPSIS

An example of use might be

use DBIWrap;

my $cfgname = 'db.cfg';
my $logical_name = 'test_db';

my $dbh = DBIWrap->DBConnect( $logical_name, $cfgname );

# Perform an immediate execution
$dbh->db_execute( 'update testusers set active=false where name like ?', $search );

# fetch a row, return a hash
my $row = $dbh->fetch_row( 'select * from testusers where name = ?', $name );

where the configuration file (which will default to $HOME/etc/db.cfg if it exists for non-root users or /etc/DBConnect.conf otherwise) has the following typical layout

# DBConnect configuration file layout

# Name a default database if no logical name is provided
DEFAULT=test_db

# connections as space-separated
# logical name, DSN, username, password and attributes

research       dbi:Pg:dbname=research2017;host=localhost researcher SEEKRET

test_db        dbi:SQLite:dbname=testdata.db

Initialisation via normal DBI method

my $dbh = DBIWrap->connect( $dsn, $user, $passwd, \%attr );

DESCRIPTION

DBIWrap is a subclass of DBI that provides for connection to databases via logical names defined in a configuration file and provides a number of additiona methods for data access and manipulation

INITIALISATION METHODS

• DBConnect

    my $dbh = DBIWrap->DBConnect( [logical db name [, config name [, user [, password ]]]] );
  

  Connect to named logical database (or default as defined in configuration file). Returns a sub-classed DBI::db object of class DBIWrap::db

• Connect

    my $dbh = DBIWrap->Connect( [logical db name [, user [, password ]]] );
  

  Connect to named logical database using default configuration file /etc/DBConnect.conf Returns a sub-classed DBI::db object of class DBIWrap::db

DBI::db EXTRA METHODS

• name

  Returns the logical database name.

• userattr

  Gets or sets an optional attribute

    $dbh->userattr( 'current_activity', 'loading archive' );
  
    $val = $dbh->userattr( 'current_activity' );
  

• is_connected

  Returns an internal state variable which is initially set to 1 on connection and then set to 0 if a ping fails.

• reconnect

  Returns a new database handle using the original connection parameters.

    $dbh = $dbh->reconnect()
        if ! $dbh->ping;
  

  This method can be used to reconnect to the database in the event of a connection failure. It will use the original connection parameters (dsn,username,password) and if successful the previous userattr will be copied across. The old handle should be discarded as suggested in the example above.

  The method can take an optional parameter which indicates that the old handle should be the return value if a new connection cannot be established. The is_connected method can then be used to determine the result (assuming the reason for reconnection is a prior loss of connection already flagged by a ping).

  If the reconnection is successful then any channels previous provided to add_listen will be re-registered.

• fetch_rows

    ($cnt,$rows) = $dbh->fetch_rows( 'select * from users where active = ?', $active_check );
  
    $rows = $dbh->fetch_rows( 'select * from users' );
  

  Performs a multi-row fetch returning either an array reference, or a count and array reference. Each entry in the array is a hash reference to an individual row. Returns an empty array reference in case of error or no results.

• fetch_row

    my $row = $dbh->fetch_row( 'select * from testusers where name = ?', $name );
  

  Return a hash reference to a single row or undef if execution errored.

• db_execute

    ($rv,$msg) = $dbh->db_execute( 'update testusers set active=false where name like ?', $search );
  
    $rv = $dbh->db_execute( 'update testusers set active=false where name like ?', $search );
  

  Execute a given given statement and return either the statement execution return value or undef. In array context will also return any database error string.

• add_listen

    $dbh->add_listen( 'event_type_1' );
  

  Adds the given notification channel to those being LISTEN-ed for.

• remove_listen

    $dbh->remove_listen( 'event_type_1' );
  

  Removes the given notification channel to those being LISTEN-ed for. Performs an UNLISTEN first.

• fetch_next_notification

  Wrapper around a pg_notifies call. Returns undef, the notification reference or the array version of it.

• get_db_fd

  Convenience wrapper around the access method to the unix fd used by the connection.

• get_seq_nbr

    ($val,$msg) = $dbh->get_seq_nbr( 'acct_nbr_seq' );
  
    $val = $dbh->get_seq_nbr( 'acct_nbr_seq' );
  

  Fetch the next sequence number from the named sequence returning either the number or undef. In array context will also return any database error string.

• show_err

    $dbh->show_err;
  
    $dbh->show_err( 'Loading File' );
  

  Display on standard error any database error, optionally prefixed with a label.

COMPATIBILITY

• DBIWrap requires DBI

AUTHOR

Bernard Quatermass toolsmith@quatermass.co.uk

COPYRIGHT AND LICENSE

This software is copyright (c) 2017, 2018, 2025 by Bernard Quatermass.

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