From 7cd9b1371d8b18d063dc38bc4fa7b30bd92c07a3 Mon Sep 17 00:00:00 2001 From: Noah Misch Date: Wed, 3 Jul 2013 07:29:23 -0400 Subject: 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. --- doc/src/sgml/libpq.sgml | 39 ++++++++++++++++++++++----------------- doc/src/sgml/plpgsql.sgml | 36 ++++++++++++++++++++++++++++++++++++ doc/src/sgml/protocol.sgml | 27 ++++++++++++++++----------- 3 files changed, 74 insertions(+), 28 deletions(-) (limited to 'doc/src') 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); PG_DIAG_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.) + 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.) @@ -2723,9 +2723,9 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_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.) + 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.) @@ -2734,9 +2734,9 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_DATATYPE_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.) + 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.) @@ -2745,11 +2745,11 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); PG_DIAG_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.) + 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.) @@ -2787,9 +2787,14 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); - 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 . + 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 . 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. 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 @@ -2664,11 +2664,36 @@ GET STACKED DIAGNOSTICS variable = item< text the SQLSTATE error code of the exception + + COLUMN_NAME + text + the name of column related to exception + + + CONSTRAINT_NAME + text + the name of constraint related to exception + + + PG_DATATYPE_NAME + text + the name of datatype related to exception + MESSAGE_TEXT text the text of the exception's primary message + + TABLE_NAME + text + the name of table related to exception + + + SCHEMA_NAME + text + the name of schema related to exception + PG_EXCEPTION_DETAIL text @@ -3355,6 +3380,17 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id; five-character SQLSTATE code. + + + COLUMN + CONSTRAINT + DATATYPE + TABLE + SCHEMA + + Supplies the name of a related object. + + 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. 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.) @@ -4801,8 +4801,8 @@ message. 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.) @@ -4814,8 +4814,8 @@ message. 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.) @@ -4827,10 +4827,10 @@ message. 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.) @@ -4876,7 +4876,12 @@ message. 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 . + see . 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. -- cgit v1.2.3