From e3161b231cfaadd4b6438eff2fc1f6cd086f41a9 Mon Sep 17 00:00:00 2001
From: Tom Lane
Date: Sun, 3 Apr 2016 12:24:54 -0400
Subject: Add libpq support for recreating an error message with different
 verbosity.

Often, upon getting an unexpected error in psql, one's first wish is that
the verbosity setting had been higher; for example, to be able to see the
schema-name field or the server code location info.  Up to now the only way
has been to adjust the VERBOSITY variable and repeat the failing query.
That's a pain, and it doesn't work if the error isn't reproducible.

This commit adds support in libpq for regenerating the error message for
an existing error PGresult at any desired verbosity level.  This is almost
just a matter of refactoring the existing code into a subroutine, but there
is one bit of possibly-needed information that was not getting put into
PGresults: the text of the last query sent to the server.  We must add that
string to the contents of an error PGresult.  But we only need to save it
if it might be used, which with the existing error-formatting code only
happens if there is a PG_DIAG_STATEMENT_POSITION error field, which is
probably pretty rare for errors in production situations.  So really the
overhead when the feature isn't used should be negligible.

Alex Shulgin, reviewed by Daniel Vérité, some improvements by me
---
 doc/src/sgml/libpq.sgml | 51 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2328d8f5f21..3829a1400d9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -2691,6 +2691,48 @@ char *PQresultErrorMessage(const PGresult *res);
       </listitem>
      </varlistentry>
 
+     <varlistentry id="libpq-pqresultverboseerrormessage">
+      <term>
+       <function>PQresultVerboseErrorMessage</function>
+       <indexterm>
+        <primary>PQresultVerboseErrorMessage</primary>
+       </indexterm>
+      </term>
+
+      <listitem>
+       <para>
+        Returns a reformatted version of the error message associated with
+        a <structname>PGresult</> object.
+<synopsis>
+char *PQresultVerboseErrorMessage(const PGresult *res,
+                                  PGVerbosity verbosity,
+                                  PGContextVisibility show_context);
+</synopsis>
+        In some situations a client might wish to obtain a more detailed
+        version of a previously-reported error.
+        <function>PQresultVerboseErrorMessage</function> addresses this need
+        by computing the message that would have been produced
+        by <function>PQresultErrorMessage</function> if the specified
+        verbosity settings had been in effect for the connection when the
+        given <structname>PGresult</> was generated.  If
+        the <structname>PGresult</> is not an error result,
+        <quote>PGresult is not an error result</> is reported instead.
+        The returned string includes a trailing newline.
+       </para>
+
+       <para>
+        Unlike most other functions for extracting data from
+        a <structname>PGresult</>, the result of this function is a freshly
+        allocated string.  The caller must free it
+        using <function>PQfreemem()</> when the string is no longer needed.
+       </para>
+
+       <para>
+        A NULL return is possible if there is insufficient memory.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="libpq-pqresulterrorfield">
       <term><function>PQresultErrorField</function><indexterm><primary>PQresultErrorField</></></term>
       <listitem>
@@ -5582,6 +5624,8 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
       mode includes all available fields.  Changing the verbosity does not
       affect the messages available from already-existing
       <structname>PGresult</> objects, only subsequently-created ones.
+      (But see <function>PQresultVerboseErrorMessage</function> if you
+      want to print a previous error with a different verbosity.)
      </para>
     </listitem>
    </varlistentry>
@@ -5622,6 +5666,8 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit
       affect the messages available from
       already-existing <structname>PGresult</> objects, only
       subsequently-created ones.
+      (But see <function>PQresultVerboseErrorMessage</function> if you
+      want to print a previous error with a different display mode.)
      </para>
     </listitem>
    </varlistentry>
@@ -6089,8 +6135,9 @@ PQsetNoticeProcessor(PGconn *conn,
    receiver function is called.  It is passed the message in the form of
    a <symbol>PGRES_NONFATAL_ERROR</symbol>
    <structname>PGresult</structname>.  (This allows the receiver to extract
-   individual fields using <function>PQresultErrorField</>, or the complete
-   preformatted message using <function>PQresultErrorMessage</>.) The same
+   individual fields using <function>PQresultErrorField</>, or obtain a
+   complete preformatted message using <function>PQresultErrorMessage</>
+   or <function>PQresultVerboseErrorMessage</>.)  The same
    void pointer passed to <function>PQsetNoticeReceiver</function> is also
    passed.  (This pointer can be used to access application-specific state
    if needed.)
-- 
cgit v1.2.3