RAISE
文を使用してメッセージを報告し、エラーを発生することができます。
RAISE [level
] 'format
' [,expression
[, ... ]] [ USINGoption
=expression
[, ... ] ]; RAISE [level
]condition_name
[ USINGoption
=expression
[, ... ] ]; RAISE [level
] SQLSTATE 'sqlstate
' [ USINGoption
=expression
[, ... ] ]; RAISE [level
] USINGoption
=expression
[, ... ]; RAISE ;
level
オプションはエラーの深刻度を指定します。
使用可能なレベルはDEBUG
、LOG
、INFO
、NOTICE
、WARNING
およびEXCEPTION
で、EXCEPTION
がデフォルトです。
EXCEPTION
はエラーを発生させ、現在のトランザクションをアボートします。
他のレベルは異なる優先度レベルのメッセージを生成するだけです。
特定の優先度のエラーメッセージがクライアントに報告するか、サーバログに書き込むか、またはその両方はlog_min_messagesおよびclient_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
付録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
USINGUSING
リスト内に書き加えます。
最後のRAISE
亜種はパラメータを全く取りません。
この形式はBEGIN
ブロックのEXCEPTION
句で使用されるのみです。
これは、現在処理中のエラーを再発生させます。
PostgreSQL9.1より前のバージョンでは、パラメータのないRAISE
は稼動している例外ハンドラを含むブロックからのエラーの再発生と解釈されました。
したがって、例外ハンドラの中で入れ子となったEXCEPTION
句は、RAISE
が入れ子となったEXCEPTION
句のブロック内にあるときでも、エラーを捕捉できないことになりました。
これは驚くべきことであり、オラクルの PL/SQLと非互換でした。
RAISE EXCEPTION
コマンド内で状況名もSQLSTATEも指定されない場合、デフォルトはRAISE_EXCEPTION
(P0001
)を使用します。
メッセージテキストが指定されない場合、デフォルトは状況名、またはSQLSTATEをメッセージテキストとして使用します。
SQLSTATEコードでエラーコードを指定する場合、事前に定義されたエラーコードに制約されることはありません。
00000
以外の5桁の数字かASCIIの大文字からなるどんなエラーコードも選択できます。
3つのゼロで終わるエラーコードの出力を避けるように推奨されています。
と言うのは、そこには分類コードがあり、それらは全ての分類から捕捉することによってのみ補足可能だからです。
ASSERT
文は、PL/pgSQL関数にデバッグ用検査を差し込むための便利な省略形です。
ASSERTcondition
[ ,message
];
condition
は常に真と評価されると想定される論理値式で、結果が真ならASSERT
文がさらに何かすることはありません。
結果が偽かNULLなら、ASSERT_FAILURE
例外が発生します。
(もし、condition
を評価する間にエラーが生じた場合、それは通常のエラーと同様に報告されます。)
省略可能なmessage
が与えられた場合、その式の結果で(NULLでないなら)、condition
に失敗した際のデフォルトエラーメッセージ文「assertion failed」が置き換えられます。
message
式はアサートに成功する通常の場合には評価されません。
アサート検査は、設定パラメータplpgsql.check_asserts
で有効または無効にできます。設定値は真偽値で、デフォルトはon
です。
off
のときには、ASSERT
文は何もしません。
ASSERT
はプログラムのバグを見つけるためのものであって、通常のエラー条件を報告するものではないことに注意してください。
そのためには前述のRAISE
を使ってください。