使用 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 配置变量控制。有关更多信息,请参见 第 19 章。
在 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
被解释为从包含活动异常处理程序的块中重新抛出错误。因此,即使 RAISE
位于嵌套的 EXCEPTION
子句的块中,嵌套在该处理程序内的 EXCEPTION
子句也无法捕获它。这被认为既令人惊讶,又与 Oracle 的 PL/SQL 不兼容。
如果在 RAISE EXCEPTION
命令中没有指定条件名称或 SQLSTATE,则默认使用 raise_exception
(P0001
)。如果没有指定消息文本,则默认使用条件名称或 SQLSTATE 作为消息文本。
当通过 SQLSTATE 代码指定错误代码时,您不仅限于预定义的错误代码,还可以选择任何由五个数字和/或大写 ASCII 字母组成的错误代码,但 00000
除外。建议您避免抛出以三个零结尾的错误代码,因为这些是类别代码,只能通过捕获整个类别来捕获。
ASSERT
语句是在 PL/pgSQL 函数中插入调试检查的便捷简写。
ASSERTcondition
[ ,message
];
condition
是一个布尔表达式,预计始终计算为 true;如果为 true,则 ASSERT
语句不再执行任何操作。如果结果为 false 或 null,则会引发 ASSERT_FAILURE
异常。(如果在评估 condition
时发生错误,则会报告为正常错误。)
如果提供了可选的 message
,它是一个表达式,其结果(如果不是 null)应在 condition
失败时替换默认错误消息文本 “断言失败”。message
表达式在断言成功的正常情况下不会进行评估。
断言的测试可以通过配置参数 plpgsql.check_asserts
启用或禁用,该参数接受一个布尔值;默认值为 on
。如果此参数为 off
,则 ASSERT
语句不执行任何操作。
请注意,ASSERT
旨在检测程序错误,而不是报告普通错误情况。为此,请使用上面描述的 RAISE
语句。
如果您在文档中发现任何不正确、与您使用特定功能的经验不符或需要进一步澄清的内容,请使用此表格报告文档问题。