★PostgreSQLカンファレンス2024 12月6日開催/チケット販売中★
他のバージョンの文書 16 | 15 | 14 | 13 | 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

43.9. エラーとメッセージ #

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

もしあれば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 #

付録Aで示されている状況名、または直接的に5文字によるSQLSTATEコードのいずれかで、報告すべきエラーコード(SQLSTATE)を指定します。

COLUMN
CONSTRAINT
DATATYPE
TABLE
SCHEMA #

関連するオブジェクト名を出力します。

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

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つのゼロで終わるエラーコードの出力を避けるように推奨されています。 と言うのは、そこには分類コードがあり、それらは全ての分類から捕捉することによってのみ補足可能だからです。

43.9.2. アサート検査 #

ASSERT文は、PL/pgSQL関数にデバッグ用検査を差し込むための便利な省略形です。

ASSERT condition [ , message ];

conditionは常に真と評価されると想定される論理値式で、結果が真ならASSERT文がさらに何かすることはありません。 結果が偽かNULLなら、ASSERT_FAILURE例外が発生します。 (もし、conditionを評価する間にエラーが生じた場合、それは通常のエラーと同様に報告されます。)

省略可能なmessageが与えられた場合、その式の結果で(NULLでないなら)、conditionに失敗した際のデフォルトエラーメッセージ文assertion failedが置き換えられます。 message式はアサートに成功する通常の場合には評価されません。

アサート検査は、設定パラメータplpgsql.check_assertsで有効または無効にできます。設定値は真偽値で、デフォルトはonです。 offのときには、ASSERT文は何もしません。

ASSERTはプログラムのバグを見つけるためのものであって、通常のエラー条件を報告するものではないことに注意してください。 そのためには前述のRAISEを使ってください。