42.8. 错误和消息

• 42 .8.1. 报告错误和消息

• 42 .8.2. 检查 assert

42 .8.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配置变量控制是否将特定优先级的消息报告给 Client 端，写入服务器日志还是同时将这两者控制。有关更多信息，请参见Chapter 19。

在* level (如果有)之后，可以编写 format *(必须是简单的字符串 Literals，而不是表达式)。格式字符串指定要报告的错误消息文本。格式字符串后可以跟可选的参数表达式，以将其插入消息中。在格式字符串中，%替换为下一个可选参数值的字符串表示形式。写%%以发出 Literals%。参数的数量必须与格式字符串中%占位符的数量匹配，否则在函数编译期间会引发错误。

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

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

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

• MESSAGE

  • 设置错误消息文本。不能以RAISE的形式使用此选项，该格式在USING之前包含格式字符串。

• DETAIL

  • 提供错误详细信息。

• HINT

  • 提供提示消息。

• ERRCODE

  • 通过条件名称(如Appendix A所示)或直接作为五字符的 SQLSTATE 代码来指定要报告的错误代码(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子句中使用；它导致当前正在处理的错误被重新抛出。

如果在RAISE EXCEPTION命令中未指定条件名称或 SQLSTATE，则默认值为使用ERRCODE_RAISE_EXCEPTION(P0001)。如果未指定消息文本，则默认值为使用条件名称或 SQLSTATE 作为消息文本。

42 .8.2. 检查 assert

ASSERT语句是将调试检查插入 PL/pgSQL 函数的便捷方式。

ASSERT condition [ , message ];

• condition 是一个布尔表达式，应始终为 true；如果是这样，则ASSERT语句不再执行任何操作。如果结果为 false 或 null，则引发ASSERT_FAILURE异常。 (如果在评估 condition *时发生错误，则将其报告为正常错误.)

如果提供了可选的* message *，则该表达式的结果(如果不为 null)将替换默认的错误消息文本“assert 失败”(如果condition 失败)。在 assert 成功的正常情况下，不会评估 message *表达式。

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

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