2025年9月25日: PostgreSQL 18 发布!
支持的版本: 当前 (18) / 17 / 16 / 15 / 14 / 13
开发版本: devel
不支持的版本: 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

32.13. 通知处理 #

服务器生成的通知和警告消息不会被查询执行函数返回,因为它们并不意味着查询失败。相反,它们会被传递给通知处理函数,并在处理函数返回后正常继续执行。默认的通知处理函数会将消息打印到 stderr,但应用程序可以通过提供自己的处理函数来覆盖此行为。

出于历史原因,通知处理分为两个级别,称为通知接收器(notice receiver)和通知处理器(notice processor)。默认行为是通知接收器格式化通知并将字符串传递给通知处理器进行打印。然而,选择提供自己的通知接收器的应用程序通常会忽略通知处理器层,而只在通知接收器中完成所有工作。

函数 PQsetNoticeReceiver 设置或检查连接对象的当前通知接收器。类似地,PQsetNoticeProcessor 设置或检查当前的通知处理器。

typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);

PQnoticeReceiver
PQsetNoticeReceiver(PGconn *conn,
                    PQnoticeReceiver proc,
                    void *arg);

typedef void (*PQnoticeProcessor) (void *arg, const char *message);

PQnoticeProcessor
PQsetNoticeProcessor(PGconn *conn,
                     PQnoticeProcessor proc,
                     void *arg);

这些函数中的每一个都会返回之前的通知接收器或处理器函数指针,并设置新值。如果你提供一个空函数指针,则不会采取任何操作,但会返回当前指针。

当从服务器收到通知或警告消息,或者由 libpq 内部生成时,会调用通知接收器函数。它会收到一个 PGRES_NONFATAL_ERROR 类型的 PGresult 格式的消息。(这允许接收器使用 PQresultErrorField 提取单个字段,或使用 PQresultErrorMessagePQresultVerboseErrorMessage 获取完整的预格式化消息。)传递给 PQsetNoticeReceiver 的同一个 void 指针也会被传递。(如果需要,此指针可用于访问应用程序特定的状态。)

默认的通知接收器会简单地提取消息(使用 PQresultErrorMessage)并将其传递给通知处理器。

通知处理器负责处理以文本形式提供的通知或警告消息。它会收到消息的文本字符串(包括一个尾随的换行符),以及一个与传递给 PQsetNoticeProcessor 相同的 void 指针。(如果需要,此指针可用于访问应用程序特定的状态。)

默认的通知处理器是简单的

static void
defaultNoticeProcessor(void *arg, const char *message)
{
    fprintf(stderr, "%s", message);
}

一旦设置了通知接收器或处理器,你应该期望该函数在 PGconn 对象或由此创建的 PGresult 对象存在期间可能会被调用。在创建 PGresult 时,PGconn 的当前通知处理指针会被复制到 PGresult 中,以供像 PQgetvalue 这样的函数可能使用。

提交更正

如果您在文档中发现任何不正确、与您对特定功能的体验不符或需要进一步阐明的内容,请使用 此表单 报告文档问题。