PostgreSQL 教程

Appearance

43.9. 错误与消息# ​

43.9.1. 报告错误与消息
43.9.2. 检查断言

43.9.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配置变量控制。有关详细信息，请参阅第 20 章。

在*level（如果有）之后，你可以指定一个format*字符串（它必须是一个简单的字符串文字，而不是一个表达式）。格式字符串指定了要报告的错误消息文本。格式字符串后面可以跟要插入到消息中的可选参数表达式。在格式字符串中，%将被替换为下一个可选参数值的字符串表示形式。编写%%以发出一个文字%。参数的数量必须与格式字符串中%占位符的数量匹配，否则将在编译函数期间引发错误。

在此示例中，v_job_id的值将替换字符串中的%

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

你可以通过编写USING后跟*option=expression项来附加附加信息到错误报告。每个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子句中使用；它会使当前正在处理的错误重新抛出。

注意

在PostgreSQL9.1 之前，没有参数的RAISE被解释为从包含活动异常处理程序的块重新抛出错误。因此，嵌套在该处理程序中的EXCEPTION子句无法捕获它，即使RAISE在嵌套EXCEPTION子句的块中也是如此。这被认为是令人惊讶的，并且与 Oracle 的 PL/SQL 不兼容。

如果在RAISE EXCEPTION命令中未指定条件名称或 SQLSTATE，则默认使用raise_exception(P0001)。如果未指定消息文本，则默认使用条件名称或 SQLSTATE 作为消息文本。

注意

通过 SQLSTATE 代码指定错误代码时，您不必局限于预定义的错误代码，但可以选择由五个数字和/或大写 ASCII 字母组成的任何错误代码，但00000除外。建议您避免抛出以三个零结尾的错误代码，因为这些是类别代码，只能通过捕获整个类别来捕获。

43.9.2. 检查断言# ​

ASSERT语句是将调试检查插入PL/pgSQL函数的便捷简写。

ASSERT condition [ , message ];

*condition是一个布尔表达式，预计它始终求值为 true；如果确实如此，则ASSERT语句不会进一步执行任何操作。如果结果为 false 或 null，则会引发ASSERT_FAILURE异常。（如果在计算condition*时发生错误，则会将其报告为正常错误。）

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

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

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