PostgreSQL 9.5.3 中文手册
上一页	上一级	章 40. PL/pgSQL - SQL过程语言	下一页

40.8. 错误和消息

40.8.1. 报告错误和消息

使用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配置变量控制。详见第 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），可以用附录 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子句中，它导致当前正在被处理的错误被重新抛出。

注意: 在PostgreSQL 9.1 之前，没有参数的RAISE被解释为重新抛出来自包含活动异常处理器的块的错误。因此一个嵌套在那个处理器中的EXCEPTION子句无法捕捉它，即使RAISE位于嵌套EXCEPTION子句的块中也是这样。这种行为很奇怪，也并不兼容 Oracle 的 PL/SQL。

如果在一个RAISE EXCEPTION命令中没有指定条件名以及 SQLSTATE，默认是使用RAISE_EXCEPTION (P0001)。如果没有指定消息文本，默认是使用条件名或 SQLSTATE 作为消息文本。

注意: 当用 SQLSTATE 代码指定一个错误代码时，你不会受到预定义错误代码的限制，而是可以选择任何由五位以及大写 ASCII 字母构成的错误代码，只有00000不能使用。我们推荐尽量避免抛出以三个零结尾的错误代码，因为这些是分类代码并且只能用来捕获整个类别。

40.8.2. 检查断言

ASSERT语句是将调试检查插入到PL/pgSQL 函数中的一个方便的简写。

ASSERT condition [ , message ];

condition是一个布尔表达式，期望总是求值为true;如果结果为true，则ASSERT语句什么也不做。如果结果为false或null，则引发一个ASSERT_FAILURE异常。（如果在计算condition时发生错误，则报告为正常错误。）

如果提供了可选的message，它是一个表达式，如果condition 失败，其结果（如果不为null）替换默认错误消息文本"断言失败"。在断言成功的正常情况下，不会评估message。

可以通过配置参数plpgsql.check_asserts启用或禁用断言测试，该配置参数采用布尔值；默认值为on。如果此参数为off，则ASSERT语句什么也不做。

注意，ASSERT是用于检测程序错误，而不是用于报告普通错误条件。要报告普通错误条件，使用上面描述的RAISE语句。