Except...ss::DBI(3pm)

💖 Exception::Class::DBI(3pm) 💖

okay bestie, gather round, because this is a User Contributed Perl Documentation page and it's about to be your new fave. we're talking Exception::Class::DBI — yes, that's the whole name, say it with your chest.

---

✨ NAME ✨

Exception::Class::DBI — DBI Exception objects, periodt. 💅

---

🌸 SYNOPSIS 🌸

like, here's the vibe in code form, no notes:

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";
}

look at that. she's beautiful. she's catching errors and printing every single diagnostic detail like the icon she is. 🫶

---

🦋 DESCRIPTION 🦋

so, what's the tea? this module hands you a whole little family of DBI-specific exception classes. they inherit from Exception::Class, which is the base class for all the exception objects made by the Exception::Class module over on the CPAN. it's giving legacy, it's giving foundation, we respect her. 👑

and Exception::Class::DBI itself? she's lowkey minimal. she offers exactly one single class method — handler() — and what that method does is return a code reference that you can pass straight into the DBI HandleError attribute. that's it. that's the whole job. slay.

the exception classes this module creates are designed to be thrown in certain DBI contexts. so the code reference that handler() gives you — the one you shoved into the DBI HandleError attribute — is what figures out the context and throws the right exception. she's the main character making the decisions. ✨

and every one of the Exception::Class::DBI classes gives you a set of object accessor methods on top of the ones Exception::Class already provides. what are they for? for outputting detailed diagnostic information when an exception happens. because when things go wrong, you want receipts. 📋

---

🎀 INTERFACE 🎀

Exception::Class::DBI inherits from Exception::Class — and therefore inherits its entire interface. the whole thing. all of it. so if you need the details on that, go read the Exception::Class documentation, iykyk. 📖

💜 Class Method 💜

• handler

okay so here's how you'd actually use it:

my $dbh = DBI->connect($data_source, $username, $auth, {
    PrintError  => 0,
    RaiseError  => 0,
    HandleError => Exception::Class::DBI->handler
});

this method returns a code reference that's appropriate for passing to the DBI HandleError attribute. that's the whole point of her existence.

now here's the lore: when DBI runs into an error, it checks its PrintError, RaiseError, and HandleError attributes to decide what to do about it. and when HandleError has been set to a code reference, DBI executes it. and it passes along three things:

1. the error string that would be printed for PrintError
2. the DBI handle object that was executing the method call that triggered the error
3. the return value of that method call — which is usually undef 😭

so using those arguments, the code reference provided by handler() determines what type of exception to throw. and Exception::Class::DBI contains the subclasses detailed below, each one relevant to the DBI handle that triggered the error.

ngl bestie, this is where it gets good — the subclasses are coming. stay tuned. 💖

---

✨ CLASSES ✨

Okay so this is the part where it gets juicy. Exception::Class::DBI spins up a whole lil squad of exception classes, and each one is specific to a particular DBI error context. Most of the object methods I'm about to describe correspond to like-named attributes in the DBI itself, so heads up: what's below is basically a summary of the DBI attribute docs. If you want the deep lore, go read DBI itself. 💅

---

🌸 Exception::Class::DBI

Every single Exception::Class::DBI class documented below inherits from Exception::Class::DBI. She offers several object methods on top of the ones she inherits from her parent, Exception::Class. These methods correspond to the DBI dynamic attributes, plus the values passed to the handler() exception handler via the DBI HandleError attribute.

Real talk: exceptions of this base class only get thrown when there's no DBI handle object executing, like in the DBI connect() method. And like… note: this functionality is not yet implemented in DBI — peep 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 holds the error string that DBI prints when its PrintError attribute is enabled, or the one it 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. Five characters, bestie, exactly.

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'll be a driver handle, for Exception::Class::DBI::DBH it'll be a database handle, and for Exception::Class::DBI::STH it'll be a statement handle. But if there's no handle thrown in the exception (because, say, the exception was thrown before a driver handle could even be created), then handle will be undef. she ghosted u

---

🦋 Exception::Class::DBI::H

This class inherits from Exception::Class::DBI, and she's the base class for all DBI handle exceptions (see below). She will not be thrown directly, no ma'am. Her methods correspond to the DBI attributes that are 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. it's giving mother of many

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. tainted data, tainted vibes

---

💜 Exception::Class::DBI::DRH

DBI driver handle exceptions objects. This class inherits from Exception::Class::DBI::H, and offers no extra methods of her own — she's simply that girl. 🌈

---

🎀 Exception::Class::DBI::DBH

DBI database handle exceptions objects. This class inherits from Exception::Class::DBI::H. Her 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. Her 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. the original three-state situationship

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 get thrown when the context for a DBI error cannot be determined. She inherits from Exception::Class::DBI, but implements no methods of her own. Mysterious. Elusive. Iconic. 💅

---

📝 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 ✨

okay so bestie, you <highkey>can</highkey> subclass Exception::Class::DBI. the <lowkey>trick</lowkey>? you gotta subclass its subclasses too. it's giving major "subclassing DBI itself" energy — the handle subclasses should exist as subnamespaces of your base subclass. 💅

It's easier to explain with an example, fr fr. Say 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/plicease/Exception-Class-DBI/). Feel free to fork and contribute! 🦋

Please file bug reports via GitHub Issues (http://github.com/plicease/Exception-Class-DBI/issues/) or by sending mail to bug-Exception-Class-DBI@rt.cpan.org (mailto:bug-Exception-Class-DBI@rt.cpan.org). 🐛

---

👑 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! 🔥

---

💖 COPYRIGHT AND LICENSE 💖

Copyright (c) 2002-2019, David E. Wheeler. Some Rights Reserved.

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

---

💖 and that's the whole manual, bestie! this page is from perl v5.34.0, dated 2022-06-30, and it's the one and only Except...ss::DBI(3pm). no cap, you're welcome. periodt. 💅✨