支持的版本: 当前 (17) / 16 / 15 / 14 / 13
开发版本: devel
不支持的版本: 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2

41.9. 错误和消息 #

41.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 选项指定错误严重性。允许的级别有 DEBUGLOGINFONOTICEWARNINGEXCEPTION,其中 EXCEPTION 是默认值。EXCEPTION 会引发错误(通常会中止当前事务);其他级别仅生成不同优先级级别的消息。是否将特定优先级的消息报告给客户端,写入服务器日志,或者两者都进行,由 log_min_messagesclient_min_messages 配置变量控制。有关更多信息,请参见 第 19 章

level (如果有)之后,您可以指定一个 format 字符串(必须是简单的字符串字面量,而不是表达式)。格式字符串指定要报告的错误消息文本。格式字符串之后可以跟可选的参数表达式,这些表达式将被插入到消息中。在格式字符串中,% 被替换为下一个可选参数值的字符串表示形式。写入 %% 来发出一个字面量 %。参数的数量必须与格式字符串中 % 占位符的数量相匹配,否则在编译函数时会引发错误。

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

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

您可以通过写入 USING,后跟 option = expression 项,将附加信息附加到错误报告中。每个 expression 都可以是任何字符串值表达式。允许的 option 关键字是

MESSAGE #

设置错误消息文本。此选项不能在 RAISE 的形式中使用,该形式在 USING 之前包含格式字符串。

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 USINGRAISE level USING,并将所有其他内容放入 USING 列表中。

RAISE 的最后一个变体根本没有参数。此形式只能在 BEGIN 块的 EXCEPTION 子句中使用;它会导致重新抛出当前正在处理的错误。

注意

PostgreSQL 9.1 之前,没有参数的 RAISE 被解释为从包含活动异常处理程序的块中重新抛出错误。因此,即使 RAISE 位于嵌套的 EXCEPTION 子句的块中,嵌套在该处理程序内的 EXCEPTION 子句也无法捕获它。这被认为既令人惊讶,又与 Oracle 的 PL/SQL 不兼容。

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

注意

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

41.9.2. 检查断言 #

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

ASSERT condition [ , message ];

condition 是一个布尔表达式,预计始终计算为 true;如果为 true,则 ASSERT 语句不再执行任何操作。如果结果为 false 或 null,则会引发 ASSERT_FAILURE 异常。(如果在评估 condition 时发生错误,则会报告为正常错误。)

如果提供了可选的 message,它是一个表达式,其结果(如果不是 null)应在 condition 失败时替换默认错误消息文本 断言失败message 表达式在断言成功的正常情况下不会进行评估。

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

请注意,ASSERT 旨在检测程序错误,而不是报告普通错误情况。为此,请使用上面描述的 RAISE 语句。

提交更正

如果您在文档中发现任何不正确、与您使用特定功能的经验不符或需要进一步澄清的内容,请使用此表格报告文档问题。