使用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;
通过写一个后面跟着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
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
是一个布尔
表达式,它被期望总是计算为真。如果确实如此,
ASSERT
语句不会再做什么。但如果结果是假
或者空,那么将发生一个ASSERT_FAILURE
异常(如果在计算
condition
时发生错误,
它会被报告为一个普通错误)。
如果提供了可选的message
,
它是一个结果(如果非空)被用来替换默认错误消息文本
“assertion failed”的表达式(如果
condition
失败)。
message
表达式在
断言成功的普通情况下不会被计算。
通过配置参数plpgsql.check_asserts
可以启用或者禁用断言测试,
这个参数接受布尔值且默认为on
。如果这个参数为off
,
则ASSERT
语句什么也不做。
注意ASSERT
是为了检测程序的 bug,而不是
报告普通的错误情况。如果要报告普通错误,请使用前面介绍的
RAISE
语句。