Provide database object names as separate fields in error messages.

This patch addresses the problem that applications currently have to
extract object names from possibly-localized textual error messages,
if they want to know for example which index caused a UNIQUE_VIOLATION
failure.  It adds new error message fields to the wire protocol, which
can carry the name of a table, table column, data type, or constraint
associated with the error.  (Since the protocol spec has always instructed
clients to ignore unrecognized field types, this should not create any
compatibility problem.)

Support for providing these new fields has been added to just a limited set
of error reports (mainly, those in the "integrity constraint violation"
SQLSTATE class), but we will doubtless add them to more calls in future.

Pavel Stehule, reviewed and extensively revised by Peter Geoghegan, with
additional hacking by Tom Lane.

4 files changed, 208 insertions, 2 deletions

diff --git a/doc/src/sgml/errcodes.sgml b/doc/src/sgml/errcodes.sgml
index 16cb6c7fcdb..40b4191c104 100644
--- a/doc/src/sgml/errcodes.sgml
+++ b/doc/src/sgml/errcodes.sgml
@@ -27,7 +27,7 @@
   According to the standard, the first two characters of an error code
   denote a class of errors, while the last three characters indicate
   a specific condition within that class.  Thus, an application that
-  does not recognize the specific error code can still be able to infer
+  does not recognize the specific error code might still be able to infer
   what to do from the error class.
  </para>
 
@@ -42,13 +42,25 @@
  </para>
 
  <para>
-  The symbol shown in the column <quote>Condition Name</quote> is also
+  The symbol shown in the column <quote>Condition Name</quote> is
   the condition name to use in <application>PL/pgSQL</>.  Condition
   names can be written in either upper or lower case.  (Note that
   <application>PL/pgSQL</> does not recognize warning, as opposed to error,
   condition names; those are classes 00, 01, and 02.)
  </para>
 
+ <para>
+  For some types of errors, the server reports the name of a database object
+  (a table, table column, data type, or constraint) associated with the error;
+  for example, the name of the unique constraint that caused a
+  <symbol>unique_violation</> error.  Such names are supplied in separate
+  fields of the error report message so that applications need not try to
+  extract them from the possibly-localized human-readable text of the message.
+  As of <productname>PostgreSQL</> 9.3, complete coverage for this feature
+  exists only for errors in SQLSTATE class 23 (integrity constraint
+  violation), but this is likely to be expanded in future.
+ </para>
+
 
 <table id="errcodes-table">
  <title><productname>PostgreSQL</productname> Error Codes</title>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index e36dd4b1d12..aa2ec2ab7bb 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -2679,6 +2679,62 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
           </listitem>
          </varlistentry>
 
+         <varlistentry id="libpq-pg-diag-schema-name">
+          <term><symbol>PG_DIAG_SCHEMA_NAME</></term>
+          <listitem>
+           <para>
+            If the error was associated with a specific database object,
+            the name of the schema containing that object, if any.
+           </para>
+          </listitem>
+         </varlistentry>
+
+         <varlistentry id="libpq-pg-diag-table-name">
+          <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.)
+           </para>
+          </listitem>
+         </varlistentry>
+
+         <varlistentry id="libpq-pg-diag-column-name">
+          <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.)
+           </para>
+          </listitem>
+         </varlistentry>
+
+         <varlistentry id="libpq-pg-diag-datatype-name">
+          <term><symbol>PG_DIAG_DATATYPE_NAME</></term>
+          <listitem>
+           <para>
+            If the error was associated with a specific datatype, the name
+            of the datatype.  (When this field is present, the schema name
+            field provides the name of the datatype's schema.)
+           </para>
+          </listitem>
+         </varlistentry>
+
+         <varlistentry id="libpq-pg-diag-constraint-name">
+          <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.)
+           </para>
+          </listitem>
+         </varlistentry>
+
          <varlistentry id="libpq-pg-diag-source-file">
           <term><symbol>PG_DIAG_SOURCE_FILE</></term>
           <listitem>
@@ -2710,6 +2766,14 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
         </variablelist>
        </para>
 
+       <note>
+        <para>
+         The fields for schema name, table name, column name, datatype
+         name, and constraint name are supplied only for a limited number
+         of error types; see <xref linkend="errcodes-appendix">.
+        </para>
+       </note>
+
        <para>
         The client is responsible for formatting displayed information to meet
         its needs; in particular it should break long lines as needed.
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index baae59de6e9..1a750593707 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -4759,6 +4759,72 @@ message.
 
 <varlistentry>
 <term>
+<literal>s</>
+</term>
+<listitem>
+<para>
+        Schema name: if the error was associated with a specific database
+        object, the name of the schema containing that object, if any.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>t</>
+</term>
+<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.)
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>c</>
+</term>
+<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.)
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>d</>
+</term>
+<listitem>
+<para>
+        Datatype name: if the error was associated with a specific datatype,
+        the name of the datatype.  (When this field is present, the schema
+        name field provides the name of the datatype's schema.)
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>n</>
+</term>
+<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.)
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
 <literal>F</>
 </term>
 <listitem>
@@ -4794,6 +4860,14 @@ message.
 
 </variablelist>
 
+<note>
+ <para>
+  The fields for schema name, table name, column name, datatype name, and
+  constraint name are supplied only for a limited number of error types;
+  see <xref linkend="errcodes-appendix">.
+ </para>
+</note>
+
 <para>
 The client is responsible for formatting displayed information to meet its
 needs; in particular it should break long lines as needed.  Newline characters
diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml
index 4ed83d6189b..4b78679d32d 100644
--- a/doc/src/sgml/sources.sgml
+++ b/doc/src/sgml/sources.sgml
@@ -275,6 +275,45 @@ ereport(ERROR,
    </listitem>
    <listitem>
     <para>
+     <function>errtable(Relation rel)</function> specifies a relation whose
+     name and schema name should be included as auxiliary fields in the error
+     report.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     <function>errtablecol(Relation rel, int attnum)</function> specifies
+     a column whose name, table name, and schema name should be included as
+     auxiliary fields in the error report.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     <function>errtableconstraint(Relation rel, const char *conname)</function>
+     specifies a table constraint whose name, table name, and schema name
+     should be included as auxiliary fields in the error report.  Indexes
+     should be considered to be constraints for this purpose, whether or
+     not they have an associated <structname>pg_constraint</> entry.  Be
+     careful to pass the underlying heap relation, not the index itself, as
+     <literal>rel</>.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     <function>errdatatype(Oid datatypeOid)</function> specifies a data
+     type whose name and schema name should be included as auxiliary fields
+     in the error report.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     <function>errdomainconstraint(Oid datatypeOid, const char *conname)</function>
+     specifies a domain constraint whose name, domain name, and schema name
+     should be included as auxiliary fields in the error report.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
      <function>errcode_for_file_access()</> is a convenience function that
      selects an appropriate SQLSTATE error identifier for a failure in a
      file-access-related system call.  It uses the saved
@@ -301,6 +340,23 @@ ereport(ERROR,
   </itemizedlist>
    </para>
 
+   <note>
+    <para>
+     At most one of the functions <function>errtable</>,
+     <function>errtablecol</>, <function>errtableconstraint</>,
+     <function>errdatatype</>, or <function>errdomainconstraint</> should
+     be used in an <function>ereport</> call.  These functions exist to
+     allow applications to extract the name of a database object associated
+     with the error condition without having to examine the
+     potentially-localized error message text.
+     These functions should be used in error reports for which it's likely
+     that applications would wish to have automatic error handling.  As of
+     <productname>PostgreSQL</> 9.3, complete coverage exists only for
+     errors in SQLSTATE class 23 (integrity constraint violation), but this
+     is likely to be expanded in future.
+    </para>
+   </note>
+
    <para>
     There is an older function <function>elog</> that is still heavily used.
     An <function>elog</> call: