40.8. 错误和消息

利用RAISE语句报告信息以及抛出错误。

RAISE [ `_level_` ] '_format_' [, `_expression_` [, ... ]] [ USING `_option_` = `_expression_` [, ... ] ];
RAISE [ `_level_` ] _condition_name_ [ USING `_option_` = `_expression_` [, ... ] ];
RAISE [ `_level_` ] SQLSTATE '_sqlstate_' [ USING `_option_` = `_expression_` [, ... ] ];
RAISE [ `_level_` ] USING _option_ = _expression_ [, ... ];
RAISE ;

_level_选项声明了错误的严重性等级。可能的级别有DEBUG,LOG, INFO, NOTICE, WARNING, 和EXCEPTION，默认的是EXCEPTION。 EXCEPTION会抛出一个错误（强制关闭当前事务），而其他级别仅仅是产生不同的优先级信息。无论是将优先级别的信息是报告给客户端，还是写到服务器日志，亦或是二者都是，都是由log_min_messages和client_min_messages配置变量控制的。参阅Chapter 18获取更多细节。

如果真有的话，在_level_之后，你可以写_format_，（这必须是一个简单的字符串文本，而不是表达式）。格式字符串声明要报告的错误信息文本。格式字符串可以遵循插入到信息中的可选参数表达式。在格式字符串里，%被下一个可选参数的外部表现形式代替。要表示%字符必须发出(%%)。

在这个例子里，v_job_id的值将代替字符串中的%：

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

你可以通过在_option_ = _expression_项后边写USING来附加额外信息到错误报告中。每一个_expression_可以是任何字符串值表达式。允许的_option_关键字是：

MESSAGE

设置错误消息文本。这个选项不能用于包含USING之前的格式字符串的RAISE形式中。

DETAIL

提供一个错误详细信息。

HINT

提供提示信息。

ERRCODE

指定错误代码（SQLSTATE）用来报告，通过条件名，如Appendix A，或直接作为五个字符的SQLSTATE代码。

COLUMN``CONSTRAINT DATATYPE TABLE SCHEMA

提供一个相关对象名称。

该例子会强制退出事务，并返回如下提示：

RAISE EXCEPTION 'Nonexistent ID --> %', user_id
      USING HINT = 'Please check your user ID';

下面两个例子在设置SQLSTATE方面具有相同的作用：

RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation';
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';

这是第二个RAISE语法，其中主要参数是条件名字或者要报告的SQLSTATE，比如：

RAISE division_by_zero;
RAISE SQLSTATE '22012';

在这个语法中，USING可以来提供一个通用的错误信息，详情，或者提示。另一个较早的例子是：

RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;

另一个变形是写RAISE USING或者RAISE``_level_ USING，然后将其他的所有东西都放在USING列中。

最后一个RAISE变形中没有任何参数。这种形式只能在BEGIN块的EXCEPTION字句中使用。它的作用是将正在处理的错误放到下一个封闭的块中。

Note: 在PostgreSQL 9.1之前，没有参数的RAISE被解释为包含有活跃异常处理程序的块中重新抛出错误。因此，EXCEPTION子句嵌套在该处理器中无法抓取它，即使 RAISE在嵌套的EXCEPTION子句块中。这被认为是令人惊讶并且不兼容Oracle的PL/SQL。

如果RAISE EXCEPTION中没有声明SQLSTATE的情形名称，那么缺省使用RAISE_EXCEPTION (P0001)。如果没有声明信息文本，那么缺省将情形名称或SQLSTATE作为信息文本。

Note: 当通过SQLSTATE编码声明一个错误代码时，你不能限制预定义错误代码，但是可以选择任何由五个数字和/或者大写ASCII字母组成的错误代码，而不是00000。建议避免抛出以三个零结尾的错误代码，因为这些是类别码并且只能通过捕获整个类别来获取。