39.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オプションはエラーの深刻度を指定します。 使用可能なレベルはDEBUG、LOG、INFO、NOTICE、WARNINGおよび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キーワードはMESSAGE、DETAIL、HINT、およびERRCODEで、それぞれのexpressionは任意の文字列で値付けされる式を取ることができます。 MESSAGEはエラーメッセージテキストを設定します （このオプションはUSINGの前に書式文字列を含むRAISE形式では使用できません）。 DETAILはエラー詳細メッセージを、一方HINTはヒントを出力します。 ERRCODEは、付録Aで示されている状況名、または直接的に５文字によるSQLSTATEコードのいずれかの報告すべきエラーコード（SQLSTATE）を指定します。

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

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';

主引数が報告されるべき状況名、またはSQLSTATEである場合、２番目の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をメッセージテキストとして使用します。