バージョンごとのドキュメント一覧

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

<title>Errors and Messages</title>

41.9.1. エラーとメッセージの報告 #

<title>Reporting Errors and Messages</title>

Use the <command>RAISE</command> statement to report messages and raise errors. 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 ;

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オプションはエラーの深刻度を指定します。 使用可能なレベルはDEBUGLOGINFONOTICEWARNINGおよび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 #
<para>Sets the error message text. This option can't be used in the form of <command>RAISE</command> that includes a format string before <literal>USING</literal>.</para>

エラーメッセージテキストを設定します。 このオプションはUSINGの前に書式文字列を含むRAISE形式では使用できません。

DETAIL #
<para>Supplies an error detail message.</para>

エラー詳細メッセージを出力します。

HINT #
<para>Supplies a hint message.</para>

ヒントメッセージを出力します。

ERRCODE #
<para>Specifies the error code (SQLSTATE) to report, either by condition name, as shown in <xref linkend="errcodes-appendix"/>, or directly as a five-character SQLSTATE code.</para>

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

COLUMN
CONSTRAINT
DATATYPE
TABLE
SCHEMA #
<para>Supplies the name of a related object.</para>

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

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 USINGと記述して、全て一括してUSINGリスト内に書き加えます。

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

41.9.2. アサート検査 #

<title>Checking Assertions</title>

The <command>ASSERT</command> statement is a convenient shorthand for inserting debugging checks into <application>PL/pgSQL</application> functions. ASSERT文は、PL/pgSQL関数にデバッグ用検査を差し込むための便利な省略形です。

ASSERT condition [ , 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を使ってください。