Postgresql 中文操作指南

43.9. Errors and Messages #

43.9.1. Reporting Errors and Messages #

使用 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配置变量控制。有关更多信息，请参见 Chapter 20。

在 level（如果有）后，你可以指定一个 format 字符串（可以是简单的字符串文本，不能是表达式）。格式字符串指定要报告的错误消息文本。格式字符串后面可以接可选参数表达式，将其插入到消息中。在格式字符串中，% 将被下一个可选参数值的字符串表示所替换。请写 %% 来发出一个文本 %。参数数量必须与格式字符串中的 % 占位符数量匹配，否则会在函数编译期间引发错误。

在此示例中，v_job_id 的值将替换字符串中的 %：

RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;

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

  • MESSAGE #

    • 设置错误消息文本。此选项不能采用 RAISE 形式使用，其中 USING 前面包含一个格式化字符串。

  • DETAIL #

    • 提供一条错误详细信息。

  • HINT #

    • Supplies a hint message.

  • 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 USING 或 RAISE _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 代码指定错误代码时，您不仅限于预定义的错误代码，还可以选择除 00000 之外的由五个数字和/或大写 ASCII 字母组成的任何错误代码。建议您避免抛出以三个零结尾的错误代码，因为这些是类别代码，只能通过捕获整个类别来捕获。

43.9.2. Checking Assertions #

ASSERT 语句是将调试检查插入到 PL/pgSQL 函数中的方便简写。

ASSERT condition [ , message ];

condition 是预计始终计算为真的布尔表达式；如果计算为真，则 ASSERT 语句不执行任何进一步的操作。如果结果为假或 null，则会引发 ASSERT_FAILURE 异常。（如果在计算 condition 时发生错误，则将其报告为一个普通错误）。

如果提供了可选的 message，它是一个表达式，如果其结果（如果非空）替换了默认的错误消息文本“断言失败”，则 condition 失败。在断言成功完成的正常情况下，不会计算 message 表达式。

可以通过配置参数 plpgsql.check_asserts 启用或禁用断言测试，此参数采用布尔值；默认值为 on。如果此参数为 off，那么 ASSERT 语句将不执行任何操作。

请注意，ASSERT_用于检测程序缺陷，而不是报告普通错误状况。为此，请使用上面描述的_RAISE 语句。