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 這樣的函式可能使用。

提交更正

如果您在文件中發現任何不正確、與您對特定功能的體驗不符或需要進一步闡明的內容,請使用 此表單 報告文件問題。