37.9. Errors and Messages

Use the RAISE statement to report messages and raise errors.

RAISE level 'format' [, variable [, ...]];

Possible levels are DEBUG, LOG, INFO, NOTICE, WARNING, and EXCEPTION. EXCEPTION raises an error and aborts the current transaction; the other levels only generate messages of different priority levels. Whether messages of a particular priority are reported to the client, written to the server log, or both is controlled by the log_min_messages and client_min_messages configuration variables. See Section 16.4 for more information.

Inside the format string, % is replaced by the next optional argument's string representation. Write %% to emit a literal %. Note that the optional arguments must presently be simple variables, not expressions, and the format must be a simple string literal.

In this example, the value of v_job_id will replace the % in the string:

RAISE NOTICE ''Calling cs_create_job(%)'', v_job_id;

This example will abort the transaction with the given error message:

RAISE EXCEPTION ''Inexistent ID --> %'', user_id;

PostgreSQL does not have a very smart exception handling model. Whenever the parser, planner/optimizer or executor decide that a statement cannot be processed any longer, the whole transaction gets aborted and the system jumps back into the main loop to get the next command from the client application.

It is possible to hook into the error mechanism to notice that this happens. But currently it is impossible to tell what really caused the abort (data type format error, floating-point error, parse error, etc.). And it is possible that the database server is in an inconsistent state at this point so returning to the upper executor or issuing more commands might corrupt the whole database.

Thus, the only thing PL/pgSQL currently does when it encounters an abort during execution of a function or trigger procedure is to add some fields to the message telling in which function and where (line number and type of statement) the error happened. The error always stops execution of the function.