他のバージョンの文書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

38.8. エラーとメッセージ

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オプションはエラーの厳格さを指定します。 使用可能なレベルはDEBUGLOGINFONOTICEWARNINGおよびEXCEPTIONで、EXCEPTIONがデフォルトです。 EXCEPTIONはエラーを発生させ、現在のトランザクションをアボートします。 他のレベルは異なる優先度レベルのメッセージを生成するだけです。 特定の優先度のエラーメッセージがクライアントに報告するか、サーバログに書き込むか、またはその両方はlog_min_messagesおよびclient_min_messages設定変数によって制御されます。 詳細については、第18章を参照してください。

もしあればlevelの後にformatを書くことができます(これは評価式ではなく、単純文字列リテラルでなければなりません)。書式文字列は報告されるエラーメッセージテキストを指定します。 書式文字列内では、%は次の省略可能な引数の値の文字列表現で書き換えられます。 %%と記述することで%リテラルを表すことができます。

以下の例では、v_job_idの値は文字列内の%を置き換えます。

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

USINGに続いて、option = expression項目を記載することで、エラー報告に追加の情報を加えることができます。使用可能なoptionキーワードは MESSAGEDETAILHINT、および ERRCODEで、それぞれのexpressionはどんな文字列で値付けされた式でも構いません。 MESSAGEはエラーメッセージテキストを設定します(このオプションはUSINGの前に書式文字列を含むRAISE形式では使用できません)。 DETAILはエラー詳細メッセージを、一方 HINTはヒントを出力します。 ERRCODEは、付録Aで示されている状況名、または直接的に5文字によるSQLSTATEコードのいずれかの報告すべきエラーコード(SQLSTATE)を指定します。

以下の例は、与えられたエラーメッセージとヒントを付けてトランザクションをアボートします。

RAISE EXCEPTION 'Nonexistent ID --> %', user_id USING HINT = 'Please check your user id';

以下の2つの例は、SQLSTATEを設定する等価な方法を示しています。

RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation';
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';

主引数が報告されるべき状況名、またはSQLSTATEである場合、2番目のRAISE構文があります。例を示します。 -->

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も指定されない場合、デフォルトはRAISE_EXCEPTION (P0001)を使用します。メッセージテキストが指定されない場合、デフォルトは状況名、またはSQLSTATEをメッセージテキストとして使用します。

注意: SQLSTATEコードでエラーコードを指定する場合、事前定義のエラーコードに制約されることはありません。00000以外の5桁の数字かASCIIの大文字からなるどんなエラーコードも選択できます。3つのゼロで終わるエラーコードの出力を避けるように推奨されています。と言うのは、そこには分類コードがあり、それらは全ての分類から捕捉することによってのみ補足可能だからです。