.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PGObject::Util::DBException 3pm"
.TH PGObject::Util::DBException 3pm "2023-11-24" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\&   PGObject::Util::DBException \-\- Database Exceptions for PGObject
.Ve
.SH "VERSION"
.IX Header "VERSION"
.Vb 1
\&   2.4.0
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   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(\*(AqPGObject::Util::DBException\*(Aq)){
\&           if ($_\->{state} eq \*(Aq23505\*(Aq) {
\&               warn "Duplicate data detected.";
\&           }
\&           log($_\->log_msg);
\&           die $_;
\&       }
\&       else {
\&           die $_;
\&       }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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.
.PP
This is optimized around database errors.  It is not intended to be a general
exception class outside the database layer.
.PP
If \f(CW\*(C`Devel::StackTrace\*(C'\fR is loaded we also capture a stack trace.
.SS "Internal Error Codes"
.IX Subsection "Internal Error Codes"
In order to handle internal PGObject errors, we rely on the fact that no
current \s-1SQL\s0 subclasses contian the letter 'A' which we will use to mean
Application.  We therefore take existing SQLState classes and use \s-1AXX\s0
(currently only A01 is used currently) to handle these errors.
.IP "26A01" 4
.IX Item "26A01"
Function not found.  No function with the discovery criteria set was found.
.IP "42A01" 4
.IX Item "42A01"
Function not unique.  Multiple functions for the discovery criteria were
found.
.SS "Stack Traces"
.IX Subsection "Stack Traces"
If \f(CW\*(C`Devel::StackTrace\*(C'\fR is loaded, we will capture stack traces starting at the
exception class call itself.
.PP
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:
\&\f(CW\*(C`PGObject::Util::DBException::STRINGIFY_STACKTRACE\*(C'\fR.  Naturally this is best
done using the \f(CW\*(C`local\*(C'\fR keyword.
.PP
Note that non-stringified stacktraces are \fBnot\fR 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.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
All constructors are called exclusively via \f(CW\*(C`$class\-\*(C'\fRmethod> syntax.
.ie n .SS "internal($state, $errstr, $query, $args);"
.el .SS "internal($state, \f(CW$errstr\fP, \f(CW$query\fP, \f(CW$args\fP);"
.IX Subsection "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.
.ie n .SS "new($dbh, $query, @args)"
.el .SS "new($dbh, \f(CW$query\fP, \f(CW@args\fP)"
.IX Subsection "new($dbh, $query, @args)"
This creates a new exception object.  The \s-1SQL\s0 State is taken from the \f(CW$dbh\fR
database handle if it is defined, and the \f(CW\*(C`DBI\*(C'\fR module if it is not.
.SH "Stringificatoin"
.IX Header "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.
.SS "short_string"
.IX Subsection "short_string"
The \f(CW\*(C`short_string\*(C'\fR method returns a short string of \f(CW\*(C`state: errstr\*(C'\fR for human
presentation.
.SS "log_msg"
.IX Subsection "log_msg"
As its name suggests, \f(CW\*(C`log_msg\*(C'\fR aimes to provide full infomation for logging
purposes.
.PP
The format here is:
.PP
.Vb 4
\&  STATE state, errstr
\&  Query: query
\&  Args: joun(\*(Aq,\*(Aq, @args)
\&  Trace: Stacktrace
.Ve