begriffs open source - ai-pg/blob - full-docs/txt/plpgsql-errors-and-messages.txt

   1
   2 41.9. Errors and Messages #
   3
   4    41.9.1. Reporting Errors and Messages
   5    41.9.2. Checking Assertions
   6
   7 41.9.1. Reporting Errors and Messages #
   8
   9    Use the RAISE statement to report messages and raise errors.
  10 RAISE [ level ] 'format' [, expression [, ... ]] [ USING option { = | := } expre
  11 ssion [, ... ] ];
  12 RAISE [ level ] condition_name [ USING option { = | := } expression [, ... ] ];
  13 RAISE [ level ] SQLSTATE 'sqlstate' [ USING option { = | := } expression [, ...
  14 ] ];
  15 RAISE [ level ] USING option { = | := } expression [, ... ];
  16 RAISE ;
  17
  18    The level option specifies the error severity. Allowed levels are
  19    DEBUG, LOG, INFO, NOTICE, WARNING, and EXCEPTION, with EXCEPTION being
  20    the default. EXCEPTION raises an error (which normally aborts the
  21    current transaction); the other levels only generate messages of
  22    different priority levels. Whether messages of a particular priority
  23    are reported to the client, written to the server log, or both is
  24    controlled by the log_min_messages and client_min_messages
  25    configuration variables. See Chapter 19 for more information.
  26
  27    In the first syntax variant, after the level if any, write a format
  28    string (which must be a simple string literal, not an expression). The
  29    format string specifies the error message text to be reported. The
  30    format string can be followed by optional argument expressions to be
  31    inserted into the message. Inside the format string, % is replaced by
  32    the string representation of the next optional argument's value. Write
  33    %% to emit a literal %. The number of arguments must match the number
  34    of % placeholders in the format string, or an error is raised during
  35    the compilation of the function.
  36
  37    In this example, the value of v_job_id will replace the % in the
  38    string:
  39 RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
  40
  41    In the second and third syntax variants, condition_name and sqlstate
  42    specify an error condition name or a five-character SQLSTATE code,
  43    respectively. See Appendix A for the valid error condition names and
  44    the predefined SQLSTATE codes.
  45
  46    Here are examples of condition_name and sqlstate usage:
  47 RAISE division_by_zero;
  48 RAISE WARNING SQLSTATE '22012';
  49
  50    In any of these syntax variants, you can attach additional information
  51    to the error report by writing USING followed by option = expression
  52    items. Each expression can be any string-valued expression. The allowed
  53    option key words are:
  54
  55    MESSAGE #
  56           Sets the error message text. This option can't be used in the
  57           first syntax variant, since the message is already supplied.
  58
  59    DETAIL #
  60           Supplies an error detail message.
  61
  62    HINT #
  63           Supplies a hint message.
  64
  65    ERRCODE #
  66           Specifies the error code (SQLSTATE) to report, either by
  67           condition name, as shown in Appendix A, or directly as a
  68           five-character SQLSTATE code. This option can't be used in the
  69           second or third syntax variant, since the error code is already
  70           supplied.
  71
  72    COLUMN
  73           CONSTRAINT
  74           DATATYPE
  75           TABLE
  76           SCHEMA #
  77           Supplies the name of a related object.
  78
  79    This example will abort the transaction with the given error message
  80    and hint:
  81 RAISE EXCEPTION 'Nonexistent ID --> %', user_id
  82       USING HINT = 'Please check your user ID';
  83
  84    These two examples show equivalent ways of setting the SQLSTATE:
  85 RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation';
  86 RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
  87
  88    Another way to produce the same result is:
  89 RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
  90
  91    As shown in the fourth syntax variant, it is also possible to write
  92    RAISE USING or RAISE level USING and put everything else into the USING
  93    list.
  94
  95    The last variant of RAISE has no parameters at all. This form can only
  96    be used inside a BEGIN block's EXCEPTION clause; it causes the error
  97    currently being handled to be re-thrown.
  98
  99 Note
 100
 101    Before PostgreSQL 9.1, RAISE without parameters was interpreted as
 102    re-throwing the error from the block containing the active exception
 103    handler. Thus an EXCEPTION clause nested within that handler could not
 104    catch it, even if the RAISE was within the nested EXCEPTION clause's
 105    block. This was deemed surprising as well as being incompatible with
 106    Oracle's PL/SQL.
 107
 108    If no condition name nor SQLSTATE is specified in a RAISE EXCEPTION
 109    command, the default is to use raise_exception (P0001). If no message
 110    text is specified, the default is to use the condition name or SQLSTATE
 111    as message text.
 112
 113 Note
 114
 115    When specifying an error code by SQLSTATE code, you are not limited to
 116    the predefined error codes, but can select any error code consisting of
 117    five digits and/or upper-case ASCII letters, other than 00000. It is
 118    recommended that you avoid throwing error codes that end in three
 119    zeroes, because these are category codes and can only be trapped by
 120    trapping the whole category.
 121
 122 41.9.2. Checking Assertions #
 123
 124    The ASSERT statement is a convenient shorthand for inserting debugging
 125    checks into PL/pgSQL functions.
 126 ASSERT condition [ , message ];
 127
 128    The condition is a Boolean expression that is expected to always
 129    evaluate to true; if it does, the ASSERT statement does nothing
 130    further. If the result is false or null, then an ASSERT_FAILURE
 131    exception is raised. (If an error occurs while evaluating the
 132    condition, it is reported as a normal error.)
 133
 134    If the optional message is provided, it is an expression whose result
 135    (if not null) replaces the default error message text “assertion
 136    failed”, should the condition fail. The message expression is not
 137    evaluated in the normal case where the assertion succeeds.
 138
 139    Testing of assertions can be enabled or disabled via the configuration
 140    parameter plpgsql.check_asserts, which takes a Boolean value; the
 141    default is on. If this parameter is off then ASSERT statements do
 142    nothing.
 143
 144    Note that ASSERT is meant for detecting program bugs, not for reporting
 145    ordinary error conditions. Use the RAISE statement, described above,
 146    for that.