使用 RAISE
语句报告消息并引发错误。
RAISE [level
] 'format
' [,expression
[, ... ]] [ USINGoption
=expression
[, ... ] ]; RAISE [level
]condition_name
[ USINGoption
=expression
[, ... ] ]; RAISE [level
] SQLSTATE 'sqlstate
' [ USINGoption
=expression
[, ... ] ]; RAISE [level
] USINGoption
=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
关键字是
此示例将使用给定的错误消息和提示中止事务
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
USINGUSING
列表中。
最后一个 RAISE
变体没有任何参数。此表单只能在 BEGIN
块的 EXCEPTION
子句中使用;它会使当前正在处理的错误重新抛出。
在 PostgreSQL 9.1 之前,没有参数的 RAISE
被解释为从包含活动异常处理程序的块重新抛出错误。因此,嵌套在该处理程序中的 EXCEPTION
子句无法捕获它,即使 RAISE
在嵌套 EXCEPTION
子句的块中也是如此。这被认为是令人惊讶的,并且与 Oracle 的 PL/SQL 不兼容。
如果在 RAISE EXCEPTION
命令中未指定条件名称或 SQLSTATE,则默认使用 raise_exception
(P0001
)。如果未指定消息文本,则默认使用条件名称或 SQLSTATE 作为消息文本。
通过 SQLSTATE 代码指定错误代码时,您不必局限于预定义的错误代码,但可以选择由五个数字和/或大写 ASCII 字母组成的任何错误代码,但 00000
除外。建议您避免抛出以三个零结尾的错误代码,因为这些是类别代码,只能通过捕获整个类别来捕获。
ASSERT
语句是将调试检查插入 PL/pgSQL 函数的便捷简写。
ASSERTcondition
[ ,message
];
condition
是一个布尔表达式,预计它始终求值为 true;如果确实如此,则 ASSERT
语句不会进一步执行任何操作。如果结果为 false 或 null,则会引发 ASSERT_FAILURE
异常。(如果在计算 condition
时发生错误,则会将其报告为正常错误。)
如果提供了可选的 message
,则它是一个表达式,其结果(如果非空)将替换默认错误消息文本 “断言失败”,如果 condition
失败。message
表达式在断言成功时的正常情况下不会被评估。
可以通过配置参数 plpgsql.check_asserts
启用或禁用断言测试,该参数采用布尔值;默认值为 on
。如果此参数为 off
,则 ASSERT
语句不执行任何操作。
请注意,ASSERT
的目的是检测程序错误,而不是报告普通错误条件。为此,请使用上面描述的 RAISE
语句。