diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/errcodes.sgml | 16 | ||||
| -rw-r--r-- | doc/src/sgml/libpq.sgml | 64 | ||||
| -rw-r--r-- | doc/src/sgml/protocol.sgml | 74 | ||||
| -rw-r--r-- | doc/src/sgml/sources.sgml | 56 |
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: |