PostgreSQL 17 文档: 41.9.错误和消息

41.9.错误和消息
上一个	向上	第 41 章. PL/pgSQL —SQL过程语言	主页	下一步

41.9. 错误和消息 #

41.9.1. 报告错误和消息
41.9.2. 检查断言

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;

可以通过编写 USING 后跟 option = expression 项来将附加信息附加到错误报告。每个 expression 可以是任何字符串值表达式。允许的 option 关键词是

MESSAGE #: 设置错误消息文本。此选项不能在 RAISE 形式中使用，该形式在 USING 之前包含一个格式字符串。
详情 #: 提供错误详情消息。
提示 #: 提供提示消息。
错误代码 #: 指定要报告的错误代码（SQLSTATE），按条件名称（如附录 A 中所示）或直接指定为五位 SQLSTATE 代码。
列 约束 数据类型 表 架构 #: 提供相关对象名称。

本示例将中止事务，并显示给定的错误消息和提示

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 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 语句不会再进行任何操作。如果结果为 false 或 null，则会引发 ASSERT_FAILURE 异常。（如果在评估 condition 时发生错误，它将作为正常错误进行报告。）

如果提供了可选的 message，它将是一个表达式，如果其结果（如果不是 null）取代了默认错误消息文本 “断言失败”，如果 condition 失败。在断言成功时的正常情况下，不会评估 message 表达式。

可以通过配置参数 plpgsql.check_asserts 启用或禁用断言的测试，它接受布尔值；默认是 on。如果此参数为 off，则 ASSERT 语句不起作用。

请注意，ASSERT 用于检测程序错误，而不是报告普通错误情况。为此，请使用上述 RAISE 语句。

上一个	向上	下一步
41.8. 事务管理	主页	41.10. 触发器函数