支援的版本:目前 (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 / 7.3 / 7.2

41.9. 錯誤和訊息 #

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 選項指定錯誤嚴重性。允許的層級為 DEBUGLOGINFONOTICEWARNINGEXCEPTION,預設為 EXCEPTIONEXCEPTION 引發錯誤(通常會中止目前的交易);其他層級僅產生不同優先順序層級的訊息。特定優先順序的訊息是否報告給用戶端、寫入伺服器日誌,或兩者都報告,由 log_min_messagesclient_min_messages 組態變數控制。請參閱 第 19 章 以取得更多資訊。

level 之後(如果有的話),您可以指定 format 字串(必須是簡單的字串常值,而不是運算式)。格式字串指定要報告的錯誤訊息文字。格式字串之後可以選擇性地加上引數運算式,以插入到訊息中。在格式字串中,% 會替換為下一個選擇性引數值的字串表示形式。寫入 %% 以發出常值 %。引數的數量必須與格式字串中 % 佔位符的數量相符,否則會在函式的編譯期間引發錯誤。

在此範例中,v_job_id 的值將替換字串中的 %

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

您可以透過寫入 USING,後接 option = expression 項目,將其他資訊附加到錯誤報告中。每個 expression 可以是任何字串值運算式。允許的 option 關鍵字包括

MESSAGE #

設定錯誤訊息文字。此選項不能用於在 USING 之前包含格式字串的 RAISE 形式中。

DETAIL #

提供錯誤詳細訊息。

HINT #

提供提示訊息。

ERRCODE #

指定要報告的錯誤代碼 (SQLSTATE),可以是條件名稱(如 附錄 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 USINGRAISE level USING,並將所有其他內容放入 USING 清單中。

RAISE 的最後一種變體沒有任何參數。此形式只能在 BEGIN 區塊的 EXCEPTION 子句中使用;它會導致重新擲回目前正在處理的錯誤。

注意

PostgreSQL 9.1 之前,沒有參數的 RAISE 會被解釋為重新拋出包含作用中例外處理器的區塊中的錯誤。因此,即使 RAISE 位於巢狀 EXCEPTION 子句的區塊中,位於該處理器內的巢狀 EXCEPTION 子句也無法捕捉到它。這被認為令人驚訝,且與 Oracle 的 PL/SQL 不相容。

如果在 RAISE EXCEPTION 命令中未指定條件名稱或 SQLSTATE,則預設使用 raise_exception (P0001)。如果未指定訊息文字,則預設使用條件名稱或 SQLSTATE 作為訊息文字。

注意

當通過 SQLSTATE 代碼指定錯誤代碼時,您不限於預定義的錯誤代碼,而是可以選擇任何由五個數字和/或大寫 ASCII 字母組成的錯誤代碼,除了 00000。建議您避免拋出以三個零結尾的錯誤代碼,因為這些是類別代碼,並且只能通過捕獲整個類別來捕獲。

41.9.2. 檢查斷言 #

ASSERT 語句是將除錯檢查插入 PL/pgSQL 函數中的便捷簡寫。

ASSERT condition [ , message ];

condition 是一個布林表達式,預期總是計算為 true;如果是,則 ASSERT 語句不會再做任何事情。如果結果為 false 或 null,則會引發 ASSERT_FAILURE 例外。(如果在評估 condition 時發生錯誤,則會將其報告為一般錯誤。)

如果提供了可選的 message,它是一個表達式,如果 condition 失敗,其結果(如果不是 null)將替換預設錯誤訊息文本 assertion failed。在斷言成功的正常情況下,不會評估 message 表達式。

斷言的測試可以通過配置參數 plpgsql.check_asserts 啟用或禁用,該參數採用布林值;預設值為 on。如果此參數為 off,則 ASSERT 語句將不做任何事情。

請注意,ASSERT 旨在檢測程式錯誤,而不是用於報告常見的錯誤狀況。使用上面描述的 RAISE 語句來處理常見錯誤狀況。

提交更正

如果您在文件中看到任何不正確、與您特定功能的使用經驗不符或需要進一步澄清的地方,請使用此表單來報告文件問題。