From 69835bc8988812c960f4ed5aeee86b62ac73602a Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 12 Sep 2017 19:27:48 -0400
Subject: Add psql variables to track success/failure of SQL queries.

This patch adds ERROR, SQLSTATE, and ROW_COUNT, which are updated after
every query, as well as LAST_ERROR_MESSAGE and LAST_ERROR_SQLSTATE,
which are updated only when a query fails.  The expected usage of these
is for scripting.

Fabien Coelho, reviewed by Pavel Stehule

Discussion: https://postgr.es/m/alpine.DEB.2.20.1704042158020.12290@lancre
---
 doc/src/sgml/ref/psql-ref.sgml | 44 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index a74caf8a6cf..60bafa81754 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -3517,6 +3517,16 @@ bar
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+       <term><varname>ERROR</varname></term>
+       <listitem>
+        <para>
+         <literal>true</> if the last SQL query failed, <literal>false</> if
+         it succeeded.  See also <varname>SQLSTATE</>.
+        </para>
+       </listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><varname>FETCH_COUNT</varname></term>
         <listitem>
@@ -3653,6 +3663,19 @@ bar
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+       <term><varname>LAST_ERROR_MESSAGE</varname></term>
+       <term><varname>LAST_ERROR_SQLSTATE</varname></term>
+       <listitem>
+        <para>
+         The primary error message and associated SQLSTATE code for the most
+         recent failed query in the current <application>psql</> session, or
+         an empty string and <literal>00000</> if no error has occurred in
+         the current session.
+        </para>
+       </listitem>
+      </varlistentry>
+
       <varlistentry>
       <term>
        <varname>ON_ERROR_ROLLBACK</varname>
@@ -3732,6 +3755,16 @@ bar
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+       <term><varname>ROW_COUNT</varname></term>
+       <listitem>
+        <para>
+         The number of rows returned or affected by the last SQL query, or 0
+         if the query failed or did not report a row count.
+        </para>
+       </listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><varname>SERVER_VERSION_NAME</varname></term>
         <term><varname>SERVER_VERSION_NUM</varname></term>
@@ -3784,6 +3817,17 @@ bar
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+       <term><varname>SQLSTATE</varname></term>
+       <listitem>
+        <para>
+         The error code (see <xref linkend="errcodes-appendix">) associated
+         with the last SQL query's failure, or <literal>00000</> if it
+         succeeded.
+        </para>
+       </listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><varname>USER</varname></term>
         <listitem>
-- 
cgit v1.2.3