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オプションはエラーの深刻度を指定します。 使用可能なレベルは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句で使用されるのみです。 これは、現在処理中のエラーを再発生させます。

注意: PostgreSQL9.1より前のバージョンでは、パラメータのないRAISEは稼動している例外ハンドラを含むブロックからのエラーの再発生と解釈されました。 したがって、例外ハンドラの中で入れ子となったEXCEPTION句は、RAISEが入れ子となったEXCEPTION句のブロック内にあるときでも、エラーを捕捉できないことになりました。 これは驚くべきことであり、オラクルの PL/SQLと非互換でした。

RAISE EXCEPTIONコマンド内で状況名もSQLSTATEも指定されない場合、デフォルトはRAISE_EXCEPTION (P0001)を使用します。 メッセージテキストが指定されない場合、デフォルトは状況名、またはSQLSTATEをメッセージテキストとして使用します。

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