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.

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.

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.

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 discusion that starts here: http://archive.develooper.com/dbi-dev@perl.org/msg01438.html.

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.

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.

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.

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.

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.

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.

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.

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.

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:

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: