Use the <command>RAISE</command> statement to report messages and
raise errors.
RAISE
文を使用してメッセージを報告し、エラーを発生することができます。
RAISE [level
] 'format
' [,expression
[, ... ]] [ USINGoption
=expression
[, ... ] ]; RAISE [level
]condition_name
[ USINGoption
=expression
[, ... ] ]; RAISE [level
] SQLSTATE 'sqlstate
' [ USINGoption
=expression
[, ... ] ]; RAISE [level
] USINGoption
=expression
[, ... ]; RAISE ;
The <replaceable class="parameter">level</replaceable> option specifies
the error severity. Allowed levels are <literal>DEBUG</literal>,
<literal>LOG</literal>, <literal>INFO</literal>,
<literal>NOTICE</literal>, <literal>WARNING</literal>,
and <literal>EXCEPTION</literal>, with <literal>EXCEPTION</literal>
being the default.
<literal>EXCEPTION</literal> raises an error (which normally aborts the
current transaction); the other levels only generate messages of different
priority levels.
Whether messages of a particular priority are reported to the client,
written to the server log, or both is controlled by the
<xref linkend="guc-log-min-messages"/> and
<xref linkend="guc-client-min-messages"/> configuration
variables. See <xref linkend="runtime-config"/> for more
information.
level
オプションはエラーの深刻度を指定します。
使用可能なレベルはDEBUG
、LOG
、INFO
、NOTICE
、WARNING
およびEXCEPTION
で、EXCEPTION
がデフォルトです。
EXCEPTION
はエラーを発生させ、現在のトランザクションをアボートします。
他のレベルは異なる優先度レベルのメッセージを生成するだけです。
特定の優先度のエラーメッセージがクライアントに報告するか、サーバログに書き込むか、またはその両方はlog_min_messagesおよびclient_min_messages設定変数によって制御されます。
詳細については、第19章を参照してください。
After <replaceable class="parameter">level</replaceable> if any,
you can specify a <replaceable class="parameter">format</replaceable> string
(which must be a simple string literal, not an expression). The
format string specifies the error message text to be reported.
The format string can be followed
by optional argument expressions to be inserted into the message.
Inside the format string, <literal>%</literal> is replaced by the
string representation of the next optional argument's value. Write
<literal>%%</literal> to emit a literal <literal>%</literal>.
The number of arguments must match the number of <literal>%</literal>
placeholders in the format string, or an error is raised during
the compilation of the function.
もしあればlevel
の後にformat
文字列を指定できます
(これは評価式ではなく、単純文字列リテラルでなければなりません)。
書式文字列は報告されるエラーメッセージテキストを指定します。
書式文字列内では、%
は次の省略可能な引数の値の文字列表現で書き換えられます。
%%
と記述することで%
リテラルを表すことができます。
引数の数は書式文字列のプレースホルダ%
の数と一致しなければいけません。さもなくば、関数のコンパイル時にエラーが起きます。
In this example, the value of <literal>v_job_id</literal> will replace the
<literal>%</literal> in the string:
以下の例では、v_job_id
の値は文字列内の%
を置き換えます。
RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
You can attach additional information to the error report by writing
<literal>USING</literal> followed by <replaceable
class="parameter">option</replaceable> = <replaceable
class="parameter">expression</replaceable> items. Each
<replaceable class="parameter">expression</replaceable> can be any
string-valued expression. The allowed <replaceable
class="parameter">option</replaceable> key words are:
USING
に続いて、option
= expression
項目を記載することで、エラー報告に追加の情報を加えることができます。
各expression
は、どのような文字列による式も可能です。
使用可能なoption
キーワードは以下です。
MESSAGE
#エラーメッセージテキストを設定します。
このオプションはUSING
の前に書式文字列を含むRAISE
形式では使用できません。
DETAIL
#エラー詳細メッセージを出力します。
HINT
#ヒントメッセージを出力します。
ERRCODE
#付録Aで示されている状況名、または直接的に5文字によるSQLSTATEコードのいずれかで、報告すべきエラーコード(SQLSTATE)を指定します。
COLUMN
CONSTRAINT
DATATYPE
TABLE
SCHEMA
#関連するオブジェクト名を出力します。
This example will abort the transaction with the given error message and hint: 以下の例は、与えられたエラーメッセージとヒントを付けてトランザクションをアボートします。
RAISE EXCEPTION 'Nonexistent ID --> %', user_id USING HINT = 'Please check your user ID';
These two examples show equivalent ways of setting the SQLSTATE: 以下の2つの例は、SQLSTATEを設定する等価な方法を示しています。
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation'; RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
There is a second <command>RAISE</command> syntax in which the main argument
is the condition name or SQLSTATE to be reported, for example:
主引数が報告されるべき状況名、またはSQLSTATEである場合、2番目のRAISE
構文があります。
例を示します。
RAISE division_by_zero; RAISE SQLSTATE '22012';
In this syntax, <literal>USING</literal> can be used to supply a custom
error message, detail, or hint. Another way to do the earlier
example is
この構文において、USING
は独自のエラーメッセージ、詳細、またはヒントを供給するように使用できます。
先の例と同じことを行う別の方法は次のようになります。
RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
Still another variant is to write <literal>RAISE USING</literal> or <literal>RAISE
<replaceable class="parameter">level</replaceable> USING</literal> and put
everything else into the <literal>USING</literal> list.
他にも亜種があり、RAISE USING
または RAISE
と記述して、全て一括してlevel
USINGUSING
リスト内に書き加えます。
The last variant of <command>RAISE</command> has no parameters at all.
This form can only be used inside a <literal>BEGIN</literal> block's
<literal>EXCEPTION</literal> clause;
it causes the error currently being handled to be re-thrown.
最後のRAISE
亜種はパラメータを全く取りません。
この形式はBEGIN
ブロックのEXCEPTION
句で使用されるのみです。
これは、現在処理中のエラーを再発生させます。
Before <productname>PostgreSQL</productname> 9.1, <command>RAISE</command> without
parameters was interpreted as re-throwing the error from the block
containing the active exception handler. Thus an <literal>EXCEPTION</literal>
clause nested within that handler could not catch it, even if the
<command>RAISE</command> was within the nested <literal>EXCEPTION</literal> clause's
block. This was deemed surprising as well as being incompatible with
Oracle's PL/SQL.
PostgreSQL9.1より前のバージョンでは、パラメータのないRAISE
は稼働している例外ハンドラを含むブロックからのエラーの再発生と解釈されました。
したがって、例外ハンドラの中で入れ子となったEXCEPTION
句は、RAISE
が入れ子となったEXCEPTION
句のブロック内にあるときでも、エラーを捕捉できないことになりました。
これは驚くべきことであり、オラクルの PL/SQLと非互換でした。
If no condition name nor SQLSTATE is specified in a
<command>RAISE EXCEPTION</command> command, the default is to use
<literal>raise_exception</literal> (<literal>P0001</literal>).
If no message text is specified, the default is to use the condition
name or SQLSTATE as message text.
RAISE EXCEPTION
コマンド内で状況名もSQLSTATEも指定されない場合、デフォルトはraise_exception
(P0001
)を使用します。
メッセージテキストが指定されない場合、デフォルトは状況名、またはSQLSTATEをメッセージテキストとして使用します。
When specifying an error code by SQLSTATE code, you are not
limited to the predefined error codes, but can select any
error code consisting of five digits and/or upper-case ASCII
letters, other than <literal>00000</literal>. It is recommended that
you avoid throwing error codes that end in three zeroes, because
these are category codes and can only be trapped by trapping
the whole category.
SQLSTATEコードでエラーコードを指定する場合、事前に定義されたエラーコードに制約されることはありません。
00000
以外の5桁の数字かASCIIの大文字からなるどんなエラーコードも選択できます。
3つのゼロで終わるエラーコードの出力を避けるように推奨されています。
と言うのは、そこには分類コードがあり、それらは全ての分類から捕捉することによってのみ補足可能だからです。
The <command>ASSERT</command> statement is a convenient shorthand for
inserting debugging checks into <application>PL/pgSQL</application>
functions.
ASSERT
文は、PL/pgSQL関数にデバッグ用検査を差し込むための便利な省略形です。
ASSERTcondition
[ ,message
];
The <replaceable class="parameter">condition</replaceable> is a Boolean
expression that is expected to always evaluate to true; if it does,
the <command>ASSERT</command> statement does nothing further. If the
result is false or null, then an <literal>ASSERT_FAILURE</literal> exception
is raised. (If an error occurs while evaluating
the <replaceable class="parameter">condition</replaceable>, it is
reported as a normal error.)
condition
は常に真と評価されると想定される論理値式で、結果が真ならASSERT
文がさらに何かすることはありません。
結果が偽かNULLなら、ASSERT_FAILURE
例外が発生します。
(もし、condition
を評価する間にエラーが生じた場合、それは通常のエラーと同様に報告されます。)
If the optional <replaceable class="parameter">message</replaceable> is
provided, it is an expression whose result (if not null) replaces the
default error message text <quote>assertion failed</quote>, should
the <replaceable class="parameter">condition</replaceable> fail.
The <replaceable class="parameter">message</replaceable> expression is
not evaluated in the normal case where the assertion succeeds.
省略可能なmessage
が与えられた場合、その式の結果で(NULLでないなら)、condition
に失敗した際のデフォルトエラーメッセージ文「assertion failed」が置き換えられます。
message
式はアサートに成功する通常の場合には評価されません。
Testing of assertions can be enabled or disabled via the configuration
parameter <literal>plpgsql.check_asserts</literal>, which takes a Boolean
value; the default is <literal>on</literal>. If this parameter
is <literal>off</literal> then <command>ASSERT</command> statements do nothing.
アサート検査は、設定パラメータplpgsql.check_asserts
で有効または無効にできます。設定値は真偽値で、デフォルトはon
です。
off
のときには、ASSERT
文は何もしません。
Note that <command>ASSERT</command> is meant for detecting program
bugs, not for reporting ordinary error conditions. Use
the <command>RAISE</command> statement, described above, for that.
ASSERT
はプログラムのバグを見つけるためのものであって、通常のエラー条件を報告するものではないことに注意してください。
そのためには前述のRAISE
を使ってください。