NAME

          PGObject::Util::DBException -- Database Exceptions for PGObject

VERSION

          2.4.0

SYNOPSIS

          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 $_;
              }

DESCRIPTION

       Database errors occur sometimes for a variety of reasons, including bugs, environmental, security, or
       user access problems, or a variety of other reasons.  For applications to appropriately handle database
       errors, it is often necessary to be able to act on categories of errors, while if we log errors for later
       analysis we want more information there.  For debugging (or even logging) we might even want to capture
       stack traces in order to try to understand where errors came from.  On the other hand, if we just want to
       display an error, we want to get an appropriate error string back.

       This class provides both options.  On one side, it provides data capture for logging, introspection, and
       analysis.  On the other it provides a short string form for display purposes.

       This is optimized around database errors.  It is not intended to be a general exception class outside the
       database layer.

       If "Devel::StackTrace" is loaded we also capture a stack trace.

   Internal Error Codes
       In order to handle internal PGObject errors, we rely on the fact that no current SQL subclasses contian
       the letter 'A' which we will use to mean Application.  We therefore take existing SQLState classes and
       use AXX (currently only A01 is used currently) to handle these errors.

       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.

       In order to be 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 to capture the
       whole  stack  trace  without  stringification,  then  you  can  set  the   following   variable   to   0:
       "PGObject::Util::DBException::STRINGIFY_STACKTRACE".   Naturally  this  is  best  done  using the "local"
       keyword.

       Note that non-stringified stacktraces are not weakened and this can cause things like database handles to
       persist for longer than they ordinarily would.  For this reason,  turning  off  stringification  is  best
       reserved for cases where it is absolutely required.

CONSTRUCTORS

       All constructors are called exclusively via "$class-"method> syntax.

   internal($state, $errstr, $query, $args);
       Used  for internal application errors.  Creates an exception of this type with these attributes.  This is
       useful for appication 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.

Stringificatoin

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

   short_string
       The "short_string" method returns a short string of "state: errstr" for human presentation.

   log_msg
       As its name suggests, "log_msg" aimes to provide full infomation for logging purposes.

       The format here is:

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

perl v5.36.0                                       2023-11-24                   PGObject::Util::DBException(3pm)