NAME
Exception::Class::DBI - DBI Exception objects
VERSION
version 1.04
Name
Exception::Class::DBI - DBI Exception objects
Synopsis
use DBI;
use Exception::Class::DBI;
my $dbh = DBI->connect($dsn, $user, $pass, {
PrintError => 0,
RaiseError => 0,
HandleError => Exception::Class::DBI->handler,
});
eval { $dbh->do($sql) };
if (my $ex = $@) {
print STDERR "DBI Exception:\n";
print STDERR " Exception Type: ", ref $ex, "\n";
print STDERR " Error: ", $ex->error, "\n";
print STDERR " Err: ", $ex->err, "\n";
print STDERR " Errstr: ", $ex->errstr, "\n";
print STDERR " State: ", $ex->state, "\n";
print STDERR " Return Value: ", ($ex->retval || 'undef'), "\n";
}
Description
This module offers a set of DBI-specific exception classes. They
inherit from Exception::Class, the base class for all exception objects
created by the Exception::Class module from the CPAN.
Exception::Class::DBI itself offers a single class method, handler(),
that returns a code reference appropriate for passing to the DBI
HandleError attribute.
The exception classes created by Exception::Class::DBI are designed to
be thrown in certain DBI contexts; the code reference returned by
handler() and passed to the DBI HandleError attribute determines the
context and throws the appropriate exception.
Each of the Exception::Class::DBI classes offers a set of object
accessor methods in addition to those provided by Exception::Class.
These can be used to output detailed diagnostic information in the
event of an exception.
Interface
Exception::Class::DBI inherits from Exception::Class, and thus its
entire interface. Refer to the Exception::Class documentation for
details.
Class Method
handler
my $dbh = DBI->connect($data_source, $username, $auth, {
PrintError => 0,
RaiseError => 0,
HandleError => Exception::Class::DBI->handler
});
This method returns a code reference appropriate for passing to the
DBI HandleError attribute. When DBI encounters an error, it checks
its PrintError, RaiseError, and HandleError attributes to decide what
to do about it. When HandleError has been set to a code reference,
DBI executes it, passing it the error string that would be printed
for PrintError, the DBI handle object that was executing the method
call that triggered the error, and the return value of that method
call (usually undef). Using these arguments, the code reference
provided by handler() determines what type of exception to throw.
Exception::Class::DBI contains the subclasses detailed below, each
relevant to the DBI handle that triggered the error.
Classes
Exception::Class::DBI creates a number of exception classes, each one
specific to a particular DBI error context. Most of the object methods
described below correspond to like-named attributes in the DBI itself.
Thus the documentation below summarizes the DBI attribute
documentation, so you should refer to DBI itself for more in-depth
information.
Exception::Class::DBI
All of the Exception::Class::DBI classes documented below inherit from
Exception::Class::DBI. It offers the several object methods in addition
to those it inherits from its parent, Exception::Class. These methods
correspond to the DBI dynamic attributes, as well as to the values
passed to the handler() exception handler via the DBI HandleError
attribute. Exceptions of this base class are only thrown when there is
no DBI handle object executing, e.g. in the DBI connect() method. Note:
This functionality is not yet implemented in DBI -- see the discussion
that starts here:
http://archive.develooper.com/dbi-dev@perl.org/msg01438.html.
error
my $error = $ex->error;
Exception::Class::DBI actually inherits this method from
Exception::Class. It contains the error string that DBI prints when
its PrintError attribute is enabled, or dies with when its
<RaiseError> attribute is enabled.
err
my $err = $ex->err;
Corresponds to the $DBI::err dynamic attribute. Returns the native
database engine error code from the last driver method called.
errstr
my $errstr = $ex->errstr;
Corresponds to the $DBI::errstr dynamic attribute. Returns the native
database engine error message from the last driver method called.
state
my $state = $ex->state;
Corresponds to the $DBI::state dynamic attribute. Returns an error
code in the standard SQLSTATE five character format.
retval
my $retval = $ex->retval;
The first value being returned by the DBI method that failed
(typically undef).
handle
my $db_handle = $ex->handle;
The DBI handle appropriate to the exception class. For
Exception::Class::DBI::DRH, it will be a driver handle. For
Exception::Class::DBI::DBH it will be a database handle. And for
Exception::Class::DBI::STH it will be a statement handle. If there is
no handle thrown in the exception (because, say, the exception was
thrown before a driver handle could be created), the handle will be
undef.
Exception::Class::DBI::H
This class inherits from Exception::Class::DBI, and is the base class
for all DBI handle exceptions (see below). It will not be thrown
directly. Its methods correspond to the DBI attributes common to all
handles.
warn
my $warn = $ex->warn;
Boolean value indicating whether DBI warnings have been enabled.
Corresponds to the DBI Warn attribute.
active
my $active = $ex->active;
Boolean value indicating whether the DBI handle that encountered the
error is active. Corresponds to the DBI Active attribute.
kids
my $kids = $ex->kids;
For a driver handle, Kids is the number of currently existing
database handles that were created from that driver handle. For a
database handle, Kids is the number of currently existing statement
handles that were created from that database handle. Corresponds to
the DBI Kids attribute.
active_kids
my $active_kids = $ex->active_kids;
Like kids, but only counting those that are active (as above).
Corresponds to the DBI ActiveKids attribute.
compat_mode
my $compat_mode = $ex->compat_mode;
Boolean value indicating whether an emulation layer (such as Oraperl)
enables compatible behavior in the underlying driver (e.g.,
DBD::Oracle) for this handle. Corresponds to the DBI CompatMode
attribute.
inactive_destroy
my $inactive_destroy = $ex->inactive_destroy;
Boolean value indicating whether the DBI has disabled the database
engine related effect of DESTROYing a handle. Corresponds to the DBI
InactiveDestroy attribute.
trace_level
my $trace_level = $ex->trace_level;
Returns the DBI trace level set on the handle that encountered the
error. Corresponds to the DBI TraceLevel attribute.
fetch_hash_key_name
my $fetch_hash_key_name = $ex->fetch_hash_key_name;
Returns the attribute name the DBI fetchrow_hashref() method should
use to get the field names for the hash keys. Corresponds to the DBI
FetchHashKeyName attribute.
chop_blanks
my $chop_blanks = $ex->chop_blanks;
Boolean value indicating whether DBI trims trailing space characters
from fixed width character (CHAR) fields. Corresponds to the DBI
ChopBlanks attribute.
long_read_len
my $long_read_len = $ex->long_read_len;
Returns the maximum length of long fields ("blob", "memo", etc.)
which the DBI driver will read from the database automatically when
it fetches each row of data. Corresponds to the DBI LongReadLen
attribute.
long_trunc_ok
my $long_trunc_ok = $ex->long_trunc_ok;
Boolean value indicating whether the DBI will truncate values it
retrieves from long fields that are longer than the value returned by
long_read_len(). Corresponds to the DBI LongTruncOk attribute.
taint
my $taint = $ex->taint;
Boolean value indicating whether data fetched from the database is
considered tainted. Corresponds to the DBI Taint attribute.
Exception::Class::DBI::DRH
DBI driver handle exceptions objects. This class inherits from
Exception::Class::DBI::H, and offers no extra methods of its own.
Exception::Class::DBI::DBH
DBI database handle exceptions objects. This class inherits from
Exception::Class::DBI::H Its methods correspond to the DBI database
handle attributes.
auto_commit
my $auto_commit = $ex->auto_commit;
Returns true if the database handle AutoCommit attribute is enabled.
meaning that database changes cannot be rolled back. Corresponds to
the DBI database handle AutoCommit attribute.
db_name
my $db_name = $ex->db_name;
Returns the "name" of the database. Corresponds to the DBI database
handle Name attribute.
statement
my $statement = $ex->statement;
Returns the statement string passed to the most recent call to the
DBI prepare() method in this database handle. If it was the prepare()
method that encountered the error and triggered the exception, the
statement string will be the statement passed to prepare().
Corresponds to the DBI database handle Statement attribute.
row_cache_size
my $row_cache_size = $ex->row_cache_size;
Returns the hint to the database driver indicating the size of the
local row cache that the application would like the driver to use for
future SELECT statements. Corresponds to the DBI database handle
RowCacheSize attribute.
Exception::Class::DBI::STH
DBI statement handle exceptions objects. This class inherits from
Exception::Class::DBI::H Its methods correspond to the DBI statement
handle attributes.
num_of_fields
my $num_of_fields = $ex->num_of_fields;
Returns the number of fields (columns) the prepared statement will
return. Corresponds to the DBI statement handle NUM_OF_FIELDS
attribute.
num_of_params
my $num_of_params = $ex->num_of_params;
Returns the number of parameters (placeholders) in the prepared
statement. Corresponds to the DBI statement handle NUM_OF_PARAMS
attribute.
field_names
my $field_names = $ex->field_names;
Returns a reference to an array of field names for each column.
Corresponds to the DBI statement handle NAME attribute.
type
my $type = $ex->type;
Returns a reference to an array of integer values for each column.
The value indicates the data type of the corresponding column.
Corresponds to the DBI statement handle TYPE attribute.
precision
my $precision = $ex->precision;
Returns a reference to an array of integer values for each column.
For non-numeric columns, the value generally refers to either the
maximum length or the defined length of the column. For numeric
columns, the value refers to the maximum number of significant digits
used by the data type (without considering a sign character or
decimal point). Corresponds to the DBI statement handle PRECISION
attribute.
scale
my $scale = $ex->scale;
Returns a reference to an array of integer values for each column.
Corresponds to the DBI statement handle SCALE attribute.
nullable
my $nullable = $ex->nullable;
Returns a reference to an array indicating the possibility of each
column returning a null. Possible values are 0 (or an empty string) =
no, 1 = yes, 2 = unknown. Corresponds to the DBI statement handle
NULLABLE attribute.
cursor_name
my $cursor_name = $ex->cursor_name;
Returns the name of the cursor associated with the statement handle,
if available. Corresponds to the DBI statement handle CursorName
attribute.
param_values
my $param_values = $ex->param_values;
Returns a reference to a hash containing the values currently bound
to placeholders. Corresponds to the DBI statement handle ParamValues
attribute.
statement
my $statement = $ex->statement;
Returns the statement string passed to the DBI prepare() method.
Corresponds to the DBI statement handle Statement attribute.
rows_in_cache
my $rows_in_cache = $ex->rows_in_cache;
the number of unfetched rows in the cache if the driver supports a
local row cache for SELECT statements. Corresponds to the DBI
statement handle RowsInCache attribute.
Exception::Class::DBI::Unknown
Exceptions of this class are thrown when the context for a DBI error
cannot be determined. Inherits from Exception::Class::DBI, but
implements no methods of its own.
Note
Note: Not all of the attributes offered by the DBI are exploited by
these exception classes. For example, the PrintError and RaiseError
attributes seemed redundant. But if folks think it makes sense to
include the missing attributes for the sake of completeness, let me
know. Enough interest will motivate me to get them in.
Subclassing
It is possible to subclass Exception::Class::DBI. The trick is to
subclass its subclasses, too. Similar to subclassing DBI itself, this
means that the handle subclasses should exist as subnamespaces of your
base subclass.
It's easier to explain with an example. Say that you wanted to add a
new method to all DBI exceptions that outputs a nicely formatted error
message. You might do it like this:
package MyApp::Ex::DBI;
use base 'Exception::Class::DBI';
sub full_message {
my $self = shift;
return $self->SUPER::full_message unless $self->can('statement');
return $self->SUPER::full_message
. ' [for Statement "'
. $self->statement . '"]';
}
You can then use this subclass just like Exception::Class::DBI itself:
my $dbh = DBI->connect($dsn, $user, $pass, {
PrintError => 0,
RaiseError => 0,
HandleError => MyApp::Ex::DBI->handler,
});
And that's all well and good, except that none of
Exception::Class::DBI's own subclasses inherit from your class, so most
exceptions won't be able to use your spiffy new method.
The solution is to create subclasses of both the Exception::Class::DBI
subclasses and your own base subclass, as long as they each use the
same package name as your subclass, plus "H", "DRH", "DBH", "STH", and
"Unknown". Here's what it looks like:
package MyApp::Ex::DBI::H;
use base 'MyApp::Ex::DBI', 'Exception::Class::DBI::H';
package MyApp::Ex::DBI::DRH;
use base 'MyApp::Ex::DBI', 'Exception::Class::DBI::DRH';
package MyApp::Ex::DBI::DBH;
use base 'MyApp::Ex::DBI', 'Exception::Class::DBI::DBH';
package MyApp::Ex::DBI::STH;
use base 'MyApp::Ex::DBI', 'Exception::Class::DBI::STH';
package MyApp::Ex::DBI::Unknown;
use base 'MyApp::Ex::DBI', 'Exception::Class::DBI::Unknown';
And then things should work just spiffy! Of course, you probably don't
need the H subclass unless you want to add other methods for the DRH,
DBH, and STH classes to inherit from.
To Do
* I need to figure out a non-database specific way of testing STH
exceptions. DBD::ExampleP works well for DRH and DBH exceptions, but
not so well for STH exceptions.
Support
This module is stored in an open GitHub repository
<http://github.com/uperl/Exception-Class-DBI/>. Feel free to fork and
contribute!
Please file bug reports via GitHub Issues
<http://github.com/uperl/Exception-Class-DBI/issues/>.
Author
Original Author is David E. Wheeler <david@justatheory.com>
Current maintainer is Graham Ollis <plicease@cpan.org>
See Also
You should really only be using this module in conjunction with Tim
Bunce's DBI, so it pays to be familiar with its documentation.
See the documentation for Dave Rolsky's Exception::Class module for
details on the methods this module's classes inherit from it. There's
lots more information in these exception objects, so use them!
AUTHORS
* David E. Wheeler <david@justatheory.com>
* Graham Ollis <plicease@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2002-2021 by David E. Wheeler.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.