バージョンごとのドキュメント一覧
PostgreSQL 16.0文書
第56章 PostgreSQLコーディング規約
誤訳等の報告
前へ 上へ56.2. サーバ内部からのエラーの報告 次へ

56.2. サーバ内部からのエラーの報告 #

<title>Reporting Errors Within the Server</title>

Error, warning, and log messages generated within the server code should be created using <function>ereport</function>, or its older cousin <function>elog</function>. The use of this function is complex enough to require some explanation. サーバコード内から生成されるエラー、警告、ログメッセージは、ereportもしくはこれに似た古いelogを使用して作成してください。 この関数の使用はいくつか説明が必要なほど複雑です。

There are two required elements for every message: a severity level (ranging from <literal>DEBUG</literal> to <literal>PANIC</literal>) and a primary message text. In addition there are optional elements, the most common of which is an error identifier code that follows the SQL spec's SQLSTATE conventions. <function>ereport</function> itself is just a shell macro that exists mainly for the syntactic convenience of making message generation look like a single function call in the C source code. The only parameter accepted directly by <function>ereport</function> is the severity level. The primary message text and any optional message elements are generated by calling auxiliary functions, such as <function>errmsg</function>, within the <function>ereport</function> call. すべてのメッセージには、深刻度レベル（DEBUGからPANICまでの範囲）と主メッセージテキストという、2つの必須要素があります。 さらに、省略可能な要素があります。 その中で最もよく使用されるのは、SQL仕様のSQLSTATE規則に従うエラー識別コードです。 ereport自身はシェルマクロで、主に、メッセージ生成をCソースコード内のひとつの関数呼び出しのように行わせる、構文の便宜上存在します。 ereportで直接受け付けられる唯一のパラメータは深刻度レベルです。 主メッセージテキストと任意の省略可能なメッセージ要素は、ereport呼び出し内でerrmsgなどの補助関数を呼び出すことで生成されます。

A typical call to <function>ereport</function> might look like this: 典型的なereportの呼び出しは以下のようなものです。 

ereport(ERROR,
        errcode(ERRCODE_DIVISION_BY_ZERO),
        errmsg("division by zero"));

This specifies error severity level <literal>ERROR</literal> (a run-of-the-mill error). The <function>errcode</function> call specifies the SQLSTATE error code using a macro defined in <filename>src/include/utils/errcodes.h</filename>. The <function>errmsg</function> call provides the primary message text. これはエラー深刻度レベルERROR（普通のエラー）を指定します。 errcode呼び出しは、src/include/utils/errcodes.hで定義されたマクロを使用してSQLSTATEエラーコードを指定します。 errmsg呼び出しは主メッセージテキストを提供します。

You will also frequently see this older style, with an extra set of parentheses surrounding the auxiliary function calls: また、補助関数の呼び出しを追加の括弧のセットで囲んだ、この古いスタイルもよく見ることでしょう。 

ereport(ERROR,
        (errcode(ERRCODE_DIVISION_BY_ZERO),
         errmsg("division by zero")));

The extra parentheses were required before <productname>PostgreSQL</productname> version 12, but are now optional. この余分な括弧はPostgreSQLバージョン12より前では必要でしたが、現在ではオプションです。

Here is a more complex example: 以下に、より複雑な例を示します。 

ereport(ERROR,
        errcode(ERRCODE_AMBIGUOUS_FUNCTION),
        errmsg("function %s is not unique",
               func_signature_string(funcname, nargs,
                                     NIL, actual_arg_types)),
        errhint("Unable to choose a best candidate function. "
                "You might need to add explicit typecasts."));

This illustrates the use of format codes to embed run-time values into a message text. Also, an optional <quote>hint</quote> message is provided. The auxiliary function calls can be written in any order, but conventionally <function>errcode</function> and <function>errmsg</function> appear first. これは、実行時の値をメッセージテキスト内に埋め込むための整形用コードの使用を示します。 また、省略可能な「ヒント」メッセージも提供されています。 補助関数の呼び出しは任意の順序で記述できますが、慣習的にerrcodeとerrmsgが最初に記述されます。

If the severity level is <literal>ERROR</literal> or higher, <function>ereport</function> aborts execution of the current query and does not return to the caller. If the severity level is lower than <literal>ERROR</literal>, <function>ereport</function> returns normally. 深刻度レベルがERROR以上であれば、ereportは現在の問い合わせの実行を中断し、呼び出し元には戻りません。 深刻度レベルがERROR未満であれば、ereportは正常に戻ります。

The available auxiliary routines for <function>ereport</function> are: ereportで使用可能な補助ルーチンを以下に示します。

注記

At most one of the functions <function>errtable</function>, <function>errtablecol</function>, <function>errtableconstraint</function>, <function>errdatatype</function>, or <function>errdomainconstraint</function> should be used in an <function>ereport</function> call. These functions exist to allow applications to extract the name of a database object associated with the error condition without having to examine the potentially-localized error message text. These functions should be used in error reports for which it's likely that applications would wish to have automatic error handling. As of <productname>PostgreSQL</productname> 9.3, complete coverage exists only for errors in SQLSTATE class 23 (integrity constraint violation), but this is likely to be expanded in future. ereport呼び出しにおいて、最大限でもerrtable、errtablecol、 errtableconstraint、errdatatype、またはerrdomainconstraintのうちの一つの関数が使用されなければなりません。 これらの関数は、アプリケーションが自動エラー対応であって欲しいと期待するエラーレポートにおいて使用されるべきです。 PostgreSQL 9.3の時点で、この機能を完璧に保証する範囲はSQLSTATEクラス23（整合性制約違反）のみですが、将来的には十中八九拡張されそうです。

There is an older function <function>elog</function> that is still heavily used. An <function>elog</function> call: まだ頻繁に使用されている、古めのelog関数があります。 以下のelog呼び出しは、 

elog(level, "format string", ...);

is exactly equivalent to: 以下とまったく同じです。 

ereport(level, errmsg_internal("format string", ...));

Notice that the SQLSTATE error code is always defaulted, and the message string is not subject to translation. Therefore, <function>elog</function> should be used only for internal errors and low-level debug logging. Any message that is likely to be of interest to ordinary users should go through <function>ereport</function>. Nonetheless, there are enough internal <quote>cannot happen</quote> error checks in the system that <function>elog</function> is still widely used; it is preferred for those messages for its notational simplicity. SQLSTATEエラーコードが常にデフォルトになること、メッセージ文字列が翻訳されないことに注意してください。 したがって、elogは、内部エラーと低レベルなデバッグ用ログにのみ使用すべきです。 一般ユーザを対象とする任意のメッセージはereportを使用すべきです。 それでもなお、システム内の「発生できなかった」内部エラーの検査にelogがまだ多く使用されています。 これは、こうした単純な表記のメッセージに適しています。

Advice about writing good error messages can be found in <xref linkend="error-style-guide"/>. 56.3に推奨するエラーメッセージの作成についての提言を示します。


[16] That is, the value that was current when the <function>ereport</function> call was reached; changes of <literal>errno</literal> within the auxiliary reporting routines will not affect it. That would not be true if you were to write <literal>strerror(errno)</literal> explicitly in <function>errmsg</function>'s parameter list; accordingly, do not do so. つまり、ereport呼び出しに達した時点の値です。 補助報告ルーチン内でerrnoを変更しても効果はありません。 errmsg内でstrerror(errno)を明示的に記述したとしても正確なものにはなりません。 したがって、このようにはしないでください。

前へ 上へ 次へ
56.1. 書式 ホーム 56.3. エラーメッセージのスタイルガイド