↑↓ 选择↵ 打开⌫ 切换范围完整搜索

PG.CENTER 连接 PostgreSQL 文档、百科与生态知识。由 Pigsty 维护。

支持中的版本: 当前版本 (18) / 17 / 16 / 15 / 14
开发中的版本: 19 / 20devel
已结束支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2

41.9. 错误和消息 #

41.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 选项指定错误的严重程度。允许的级别为 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;

在第二和第三种语法变体中,condition_name 和 sqlstate 分别指定错误条件名称或五字符 SQLSTATE 代码。有效的错误条件名称和预定义 SQLSTATE 代码见附录 A。

下面是 condition_name 和 sqlstate 的用法示例:

RAISE division_by_zero;
RAISE WARNING SQLSTATE '22012';

在任意一种语法变体中,都可以通过写一个后面跟着 option = expression 项的 USING,为错误报告附加额外信息。每一个 expression 可以是任意字符串值的表达式。允许的 option 关键词是:

MESSAGE #

设置错误消息文本。该选项不能用于第一种语法变体,因为消息文本已经给出。

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 unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;

如第四种语法变体所示,也可以写成 RAISE USING 或 RAISE level USING,并把其余内容都放在 USING 列表里。

RAISE 的最后一种变体根本没有参数。这种形式只能被用在一个 BEGIN 块的 EXCEPTION 子句中,它导致当前正在被处理的错误被重新抛出。

注意

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

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

注意

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

41.9.2. 检查断言 #

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

ASSERT condition [ , message ];

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

可选的 message 是一个表达式。如果提供了该表达式,且 condition 失败,其结果(如果不为 NULL)将替换默认错误消息文本“assertion failed”。message 表达式在断言成功的普通情况下不会被计算。

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

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

报告文档问题

阅读 上游文档. 通过 PostgreSQL 文档反馈表单.