选择 打开 改范围 完整检索页
受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10
当前 PostgreSQL 版本不在支持生命周期内。
您可以参阅当前版本的对应页面,或其他在上面列出的活跃大版本。

42.9. 错误和消息 #

42.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选项指定错误的严重程度。允许的级别为DEBUGLOGINFONOTICEWARNING以及EXCEPTION,其中EXCEPTION是默认值。EXCEPTION会抛出错误(通常会中止当前事务);其他级别只会生成不同优先级的消息。特定优先级的消息是报告给客户端、写入服务器日志,还是两者都做,由log_min_messagesclient_min_messages配置变量控制。更多信息见Chapter 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),可以使用Appendix 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子句内部;它会重新抛出当前正在处理的错误。

Note

PostgreSQL 9.1 之前,没有参数的RAISE被解释为重新抛出来自包含活动异常处理器的块的错误。因此一个嵌套在那个处理器中的EXCEPTION子句无法捕捉它,即使RAISE位于嵌套EXCEPTION子句的块中也是这样。这种行为很奇怪,也并不兼容 Oracle 的 PL/SQL。

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

Note

当用 SQLSTATE 代码指定错误代码时,你并不受限于预定义错误代码,而是可以选择任何由五位数字和/或大写 ASCII 字母构成的错误代码,唯一不能使用的是 00000。我们建议尽量避免抛出以三个零结尾的错误代码,因为这些是类别代码,只能用于捕获整个类别。

42.9.2. 检查断言 #

ASSERT语句是一种向 PL/pgSQL函数中插入调试检查的方便方法。

ASSERT condition [ , message ];

condition是一个布尔 表达式,它被期望总是计算为真。如果确实如此, ASSERT语句不会再做什么。但如果结果是假 或者空,那么将发生一个ASSERT_FAILURE异常(如果在计算 condition时发生错误, 它会被报告为一个普通错误)。

如果提供了可选的message, 它是一个结果(如果非空)被用来替换默认错误消息文本 assertion failed的表达式(如果 condition失败)。 message表达式在 断言成功的普通情况下不会被计算。

通过配置参数plpgsql.check_asserts可以启用或者禁用断言测试, 这个参数接受布尔值且默认为on。如果这个参数为off, 则ASSERT语句什么也不做。

注意ASSERT是为了检测程序的 bug,而不是 报告普通的错误情况。如果要报告普通错误,请使用前面介绍的 RAISE语句。