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