pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。
使用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配置变量控制。更多信息见第 18 章中的说明。
在level(如果有)之后,可以写一个format(必须是简单的字符串字面量,不能是表达式)。格式字符串指定要报告的错误消息文本。格式字符串之后可以跟上可选的参数表达式,其值将被插入消息中。在格式字符串内,%会被替换为下一个可选参数值的字符串表示。写成%%可以输出一个字面的%。
在这个示例中,v_job_id的值将替换字符串中的%:
RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
可以为错误报告附加额外信息,方法是写出USING,后面跟上option = expression项目。每个expression都可以是任意字符串值表达式。允许的option关键字为:
MESSAGE设置错误消息文本。该选项不能用于在USING之前包含格式字符串的RAISE形式。
DETAIL提供错误的详细信息。
HINT提供一个提示消息。
ERRCODE指定要报告的错误代码(SQLSTATE),可以用附录 A中所示的条件名,或者直接作为一个五字符 SQLSTATE 代码。
COLUMNCONSTRAINTDATATYPETABLESCHEMA提供一个相关对象的名称。
这个例子会中止事务,并给出指定的错误消息和提示:
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, 则默认使用ERRCODE_RAISE_EXCEPTION (P0001)。 如果没有指定消息文本,则默认使用条件名称或SQLSTATE作为消息文本。
当用 SQLSTATE 代码指定错误代码时,你并不受限于预定义错误代码,而是可以选择任何由五位数字和/或大写 ASCII 字母构成的错误代码,唯一不能使用的是 00000。我们建议尽量避免抛出以三个零结尾的错误代码,因为这些是类别代码,只能通过捕获整个类别来捕获这类错误。
译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。