PGObje...ception(3pm)

okay bestie, welcome to the PGObje...ception(3pm) page — yeah that's the little truncated nickname she goes by, and she lives in the User Contributed Perl Documentation, section 3pm. full name is right down there 👇

💖 NAME 💖

PGObject::Util::DBException — Database Exceptions for PGObject. that's it, that's the name, she's iconic 💅

🌸 VERSION 🌸

2.4.0 ✨

---

🦋 SYNOPSIS 🦋

okay so here's how you actually use her:

use PGObject::Util::DBException;

$dbh->execute(@args) || die
    PGObject::Util::DBException->new($dbh, $query, @args);

# if you need something without dbh:

die PGObject::Util::DBException->internal($state, $string, $query, $args);

# if $dbh is undef, then we assume it is a connection error and ask DBI

# in a handler you can check
try {
    some_db_func();
} catch {
    if ($_->isa('PGObject::Util::DBException')){
        if ($_->{state} eq '23505') {
            warn "Duplicate data detected.";
        }
        log($_->log_msg);
        die $_;
    }
    else {
        die $_;
    }

literally so much going on and yet it all makes sense. slay. 💜

🌈 DESCRIPTION 🌈

okay so real talk: database errors happen. sometimes it's a bug, sometimes it's the environment, sometimes it's security, sometimes it's a user access problem, sometimes it's just... a variety of other reasons. life is like that. 😭

and here's the thing — apps need to be able to act on categories of errors (like, group them up and handle them), but when we're logging errors for later analysis we want way more info in there. and for debugging (or even just logging) we might highkey want a stack trace so we can figure out where the error even came from. but on the other hand, if we just wanna show someone an error, we want a nice short error string back. mood.

this class does both. on one side she's giving data capture for logging, introspection, and analysis. on the other side she's giving a short string form for display purposes. versatile queen. 👑

and she is optimized around database errors specifically. she is not intended to be a general exception class outside the database layer. stay in your lane bestie, and she does. 🫶

if Devel::StackTrace is loaded we also capture a stack trace. noted. ✨

🧚 Internal Error Codes 🧚

so to handle internal PGObject errors, we rely on the fact that no current SQL subclasses contain the letter 'A' — and we're using that 'A' to mean Application. so we take the existing SQLState classes and use AXX (currently only A01 is used currently) to handle these errors. clever, honestly.

• 26A01 — Function not found. No function with the discovery criteria set was found. 💀
• 42A01 — Function not unique. Multiple functions for the discovery criteria were found. 🙈

🎀 Stack Traces 🎀

if Devel::StackTrace is loaded, we will capture stack traces starting at the exception class call itself.

and to keep things unobtrusive, these are stringified by default. this is to avoid problems of reference counting and lifecycle that can happen when capturing tracing information. if you want the whole entire stack trace without stringification, you can set this variable to 0:

PGObject::Util::DBException::STRINGIFY_STACKTRACE

and naturally the best way to do that is with the local keyword. iykyk. ✨

⚠️ heads up bestie: non-stringified stacktraces are not weakened, and this can cause things like database handles to persist for longer than they ordinarily would. so turning off stringification is best reserved for cases where it is absolutely required. don't be reckless. 💀

---

👑 CONSTRUCTORS 👑

all constructors are called exclusively via $class->method syntax. periodt.

💜 internal($state, $errstr, $query, $args);

used for internal application errors. creates an exception of this type with these attributes. this is useful for application errors within the PGObject framework. 🫶

💜 new($dbh, $query, @args)

this creates a new exception object. the SQL State is taken from the $dbh database handle if it is defined, and the DBI module if it is not. easy.

---

💅 Stringificatoin 💅

(yes, that heading has a lil typo in the original and we are keeping it exactly as-is, she's iconic that way 💖)

this module provides two methods for string representation. the first one, for human-focused error messages, also overloads stringification generally. the second one is primarily intended for logging purposes.

🌸 short_string

the short_string method returns a short string of state: errstr for human presentation. cute, quick, to the point.

🌸 log_msg

as its name suggests, log_msg aimes to provide full infomation for logging purposes. (again, typos preserved, no notes 💀)

the format here is:

STATE state, errstr
Query: query
Args: joun(',', @args)
Trace: Stacktrace

---

🎀 and that's the whole page, bestie. you now know her better than most people know themselves.

and finally, the lil sign-off at the bottom of the page: this beauty is served up by perl v5.36.0 and dated 2023-11-24, on the PGObje...ception(3pm) page. go forth and catch those exceptions. no cap. ✨💖🌈