Expose object name error fields in PL/pgSQL.

Specifically, permit attaching them to the error in RAISE and retrieving
them from a caught error in GET STACKED DIAGNOSTICS.  RAISE enforces
nothing about the content of the fields; for its purposes, they are just
additional string fields.  Consequently, clarify in the protocol and
libpq documentation that the usual relationships between error fields,
like a schema name appearing wherever a table name appears, are not
universal.  This freedom has other applications; consider a FDW
propagating an error from an RDBMS having no schema support.

Back-patch to 9.3, where core support for the error fields was
introduced.  This prevents the confusion of having a release where libpq
exposes the fields and PL/pgSQL does not.

Pavel Stehule, lexical revisions by Noah Misch.

3 files changed, 74 insertions, 28 deletions

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 07db5e4d356..a3c7de8b89b 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -2712,9 +2712,9 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
           <term><symbol>PG_DIAG_TABLE_NAME</></term>
           <listitem>
            <para>
-            If the error was associated with a specific table, the name of
-            the table.  (When this field is present, the schema name field
-            provides the name of the table's schema.)
+            If the error was associated with a specific table, the name of the
+            table.  (Refer to the schema name field for the name of the
+            table's schema.)
            </para>
           </listitem>
          </varlistentry>
@@ -2723,9 +2723,9 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
           <term><symbol>PG_DIAG_COLUMN_NAME</></term>
           <listitem>
            <para>
-            If the error was associated with a specific table column, the
-            name of the column.  (When this field is present, the schema
-            and table name fields identify the table.)
+            If the error was associated with a specific table column, the name
+            of the column.  (Refer to the schema and table name fields to
+            identify the table.)
            </para>
           </listitem>
          </varlistentry>
@@ -2734,9 +2734,9 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
           <term><symbol>PG_DIAG_DATATYPE_NAME</></term>
           <listitem>
            <para>
-            If the error was associated with a specific data type, the name
-            of the data type.  (When this field is present, the schema name
-            field provides the name of the data type's schema.)
+            If the error was associated with a specific data type, the name of
+            the data type.  (Refer to the schema name field for the name of
+            the data type's schema.)
            </para>
           </listitem>
          </varlistentry>
@@ -2745,11 +2745,11 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
           <term><symbol>PG_DIAG_CONSTRAINT_NAME</></term>
           <listitem>
            <para>
-            If the error was associated with a specific constraint,
-            the name of the constraint.  The table or domain that the
-            constraint belongs to is reported using the fields listed
-            above.  (For this purpose, indexes are treated as constraints,
-            even if they weren't created with constraint syntax.)
+            If the error was associated with a specific constraint, the name
+            of the constraint.  Refer to fields listed above for the
+            associated table or domain.  (For this purpose, indexes are
+            treated as constraints, even if they weren't created with
+            constraint syntax.)
            </para>
           </listitem>
          </varlistentry>
@@ -2787,9 +2787,14 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
 
        <note>
         <para>
-         The fields for schema name, table name, column name, data type
-         name, and constraint name are supplied only for a limited number
-         of error types; see <xref linkend="errcodes-appendix">.
+         The fields for schema name, table name, column name, data type name,
+         and constraint name are supplied only for a limited number of error
+         types; see <xref linkend="errcodes-appendix">.  Do not assume that
+         the presence of any of these fields guarantees the presence of
+         another field.  Core error sources observe the interrelationships
+         noted above, but user-defined functions may use these fields in other
+         ways.  In the same vein, do not assume that these fields denote
+         contemporary objects in the current database.
         </para>
        </note>
 
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 19498c67676..6fffec18b70 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -2665,11 +2665,36 @@ GET STACKED DIAGNOSTICS <replaceable>variable</replaceable> = <replaceable>item<
          <entry>the SQLSTATE error code of the exception</entry>
         </row>
         <row>
+         <entry><literal>COLUMN_NAME</literal></entry>
+         <entry>text</entry>
+         <entry>the name of column related to exception</entry>
+        </row>
+        <row>
+         <entry><literal>CONSTRAINT_NAME</literal></entry>
+         <entry>text</entry>
+         <entry>the name of constraint related to exception</entry>
+        </row>
+        <row>
+         <entry><literal>PG_DATATYPE_NAME</literal></entry>
+         <entry>text</entry>
+         <entry>the name of datatype related to exception</entry>
+        </row>
+        <row>
          <entry><literal>MESSAGE_TEXT</literal></entry>
          <entry>text</entry>
          <entry>the text of the exception's primary message</entry>
         </row>
         <row>
+         <entry><literal>TABLE_NAME</literal></entry>
+         <entry>text</entry>
+         <entry>the name of table related to exception</entry>
+        </row>
+        <row>
+         <entry><literal>SCHEMA_NAME</literal></entry>
+         <entry>text</entry>
+         <entry>the name of schema related to exception</entry>
+        </row>
+        <row>
          <entry><literal>PG_EXCEPTION_DETAIL</literal></entry>
          <entry>text</entry>
          <entry>the text of the exception's detail message, if any</entry>
@@ -3355,6 +3380,17 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
         five-character SQLSTATE code.</para>
       </listitem>
      </varlistentry>
+
+     <varlistentry>
+      <term><literal>COLUMN</literal></term>
+      <term><literal>CONSTRAINT</literal></term>
+      <term><literal>DATATYPE</literal></term>
+      <term><literal>TABLE</literal></term>
+      <term><literal>SCHEMA</literal></term>
+      <listitem>
+       <para>Supplies the name of a related object.</para>
+      </listitem>
+     </varlistentry>
     </variablelist>
    </para>
 
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index f1cafa59d24..0b2e60eeb13 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -4788,8 +4788,8 @@ message.
 <listitem>
 <para>
         Table name: if the error was associated with a specific table, the
-        name of the table.  (When this field is present, the schema name field
-        provides the name of the table's schema.)
+        name of the table.  (Refer to the schema name field for the name of
+        the table's schema.)
 </para>
 </listitem>
 </varlistentry>
@@ -4801,8 +4801,8 @@ message.
 <listitem>
 <para>
         Column name: if the error was associated with a specific table column,
-        the name of the column.  (When this field is present, the schema and
-        table name fields identify the table.)
+        the name of the column.  (Refer to the schema and table name fields to
+        identify the table.)
 </para>
 </listitem>
 </varlistentry>
@@ -4814,8 +4814,8 @@ message.
 <listitem>
 <para>
         Data type name: if the error was associated with a specific data type,
-        the name of the data type.  (When this field is present, the schema
-        name field provides the name of the data type's schema.)
+        the name of the data type.  (Refer to the schema name field for the
+        name of the data type's schema.)
 </para>
 </listitem>
 </varlistentry>
@@ -4827,10 +4827,10 @@ message.
 <listitem>
 <para>
         Constraint name: if the error was associated with a specific
-        constraint, the name of the constraint.  The table or domain that the
-        constraint belongs to is reported using the fields listed above.  (For
-        this purpose, indexes are treated as constraints, even if they weren't
-        created with constraint syntax.)
+        constraint, the name of the constraint.  Refer to fields listed above
+        for the associated table or domain.  (For this purpose, indexes are
+        treated as constraints, even if they weren't created with constraint
+        syntax.)
 </para>
 </listitem>
 </varlistentry>
@@ -4876,7 +4876,12 @@ message.
  <para>
   The fields for schema name, table name, column name, data type name, and
   constraint name are supplied only for a limited number of error types;
-  see <xref linkend="errcodes-appendix">.
+  see <xref linkend="errcodes-appendix">.  Frontends should not assume that
+  the presence of any of these fields guarantees the presence of another
+  field.  Core error sources observe the interrelationships noted above, but
+  user-defined functions may use these fields in other ways.  In the same
+  vein, clients should not assume that these fields denote contemporary
+  objects in the current database.
  </para>
 </note>