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>, defined
in <filename>src/include/utils/elog.h</filename>) 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.
《マッチ度[87.081340]》すべてのメッセージには、深刻度レベル（DEBUGからPANICまでの範囲）と主メッセージテキストという、2つの必須要素があります。
さらに、省略可能な要素があります。
その中で最もよく使用されるのは、SQL仕様のSQLSTATE規則に従うエラー識別コードです。
ereport自身はシェルマクロで、主に、メッセージ生成をCソースコード内のひとつの関数呼び出しのように行わせる、構文の便宜上存在します。
ereportで直接受け付けられる唯一のパラメータは深刻度レベルです。
主メッセージテキストと任意の省略可能なメッセージ要素は、ereport呼び出し内でerrmsgなどの補助関数を呼び出すことで生成されます。
《機械翻訳》各メッセージには2つの必須要素があります。
重要度レベル（src/include/utils/elog.hで定義される、includeからPANICまでの範囲）とプライマリメッセージテキストです。
さらに、オプショナル要素があり、その中で最も一般的なものは、エラー仕様のSQLSTATEコードに従うSQL識別子規約です。
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で使用可能な補助ルーチンを以下に示します。
<function>errcode(sqlerrcode)</function> specifies the SQLSTATE error identifier
code for the condition. If this routine is not called, the error
identifier defaults to
<literal>ERRCODE_INTERNAL_ERROR</literal> when the error severity level is
<literal>ERROR</literal> or higher, <literal>ERRCODE_WARNING</literal> when the
error level is <literal>WARNING</literal>, otherwise (for <literal>NOTICE</literal>
and below) <literal>ERRCODE_SUCCESSFUL_COMPLETION</literal>.
While these defaults are often convenient, always think whether they
are appropriate before omitting the <function>errcode()</function> call.
errcode(sqlerrcode)は、その条件用のSQLSTATEエラー識別コードを指定します。
このルーチンが呼び出されないと、エラー識別子のデフォルトは、エラー深刻度レベルがERROR以上の場合にはERRCODE_INTERNAL_ERRORに、エラー深刻度レベルがWARNINGの場合にはERRCODE_WARNINGに、さもなければ（NOTICE以下）ERRCODE_SUCCESSFUL_COMPLETIONになります。
これらのデフォルトはしばしば便利ですが、errcode()呼び出しを省略する前に、常に適切かどうかを検討してください。
<function>errmsg(const char *msg, ...)</function> specifies the primary error
message text, and possibly run-time values to insert into it. Insertions
are specified by <function>sprintf</function>-style format codes. In addition to
the standard format codes accepted by <function>sprintf</function>, the format
code <literal>%m</literal> can be used to insert the error message returned
by <function>strerror</function> for the current value of <literal>errno</literal>.
errmsg(const char *msg, ...)は、主エラーメッセージテキストを指定し、また、実行時の値をそこに挿入することもできます。
挿入は、sprintf様式の書式コードで指定されます。
sprintfで受け付けられる標準の書式コードに加え、%m書式コードを使用して、現在のerrnoの値用のstrerrorで返されるエラーメッセージを挿入することができます。
[16]
<literal>%m</literal> does not require any
corresponding entry in the parameter list for <function>errmsg</function>.
Note that the message string will be run through <function>gettext</function>
for possible localization before format codes are processed.
%mはerrmsgのパラメータリスト内に対応する項目を必要としません。
メッセージ文字列は、書式コードの処理を行う前に、ローカライゼーションのためにgettextを通ることに注意してください。
<function>errmsg_internal(const char *msg, ...)</function> is the same as
<function>errmsg</function>, except that the message string will not be
translated nor included in the internationalization message dictionary.
This should be used for <quote>cannot happen</quote> cases that are probably
not worth expending translation effort on.
errmsg_internal(const char *msg, ...)は、そのメッセージ文字列は翻訳されず、国際化用メッセージ辞書に含まれない点を除き、errmsgと同一です。
これは、おそらく翻訳作業を行う価値がない「発生し得ない」場合用に使用すべきです。
<function>errmsg_plural(const char *fmt_singular, const char *fmt_plural,
unsigned long n, ...)</function> is like <function>errmsg</function>, but with
support for various plural forms of the message.
<replaceable>fmt_singular</replaceable> is the English singular format,
<replaceable>fmt_plural</replaceable> is the English plural format,
<replaceable>n</replaceable> is the integer value that determines which plural
form is needed, and the remaining arguments are formatted according
to the selected format string. For more information see
<xref linkend="nls-guidelines"/>.
errmsg_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n, ...)はerrmsgのようですが、メッセージの各種の複数書式があります。
fmt_singularは英語の単数書式、fmt_pluralは英語の複数書式、nはどの複数書式が必要なのかを決定する整数値で、残りの引数は選択された書式文字列に従って書式化されます。
より詳細な情報は55.2.2を参照してください。
<function>errdetail(const char *msg, ...)</function> supplies an optional
<quote>detail</quote> message; this is to be used when there is additional
information that seems inappropriate to put in the primary message.
The message string is processed in just the same way as for
<function>errmsg</function>.
errdetail(const char *msg, ...)は省略可能な「詳細」メッセージを提供します。
これは、主メッセージ内に記述するには不適切と考えられる追加情報がある場合に使用されます。
このメッセージ文字列はerrmsgとまったく同じ方法で処理されます。
<function>errdetail_internal(const char *msg, ...)</function> is the same
as <function>errdetail</function>, except that the message string will not be
translated nor included in the internationalization message dictionary.
This should be used for detail messages that are not worth expending
translation effort on, for instance because they are too technical to be
useful to most users.
errdetail_internal(const char *msg, ...)は、メッセージが翻訳されない、または、国際化メッセージ辞書内に含まれない点を除き、errdetailと同じです。
これは、例えばほとんどのユーザに役に立つにはあまりにも技術的すぎるなど、翻訳する手間をかける価値がない詳細メッセージで有用であるはずです。
<function>errdetail_plural(const char *fmt_singular, const char *fmt_plural,
unsigned long n, ...)</function> is like <function>errdetail</function>, but with
support for various plural forms of the message.
For more information see <xref linkend="nls-guidelines"/>.
errdetail_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n, ...)はerrdetailと似ていますが、メッセージの各種の複数書式をサポートします。
より詳細な情報は55.2.2を参照してください。
<function>errdetail_log(const char *msg, ...)</function> is the same as
<function>errdetail</function> except that this string goes only to the server
log, never to the client. If both <function>errdetail</function> (or one of
its equivalents above) and
<function>errdetail_log</function> are used then one string goes to the client
and the other to the log. This is useful for error details that are
too security-sensitive or too bulky to include in the report
sent to the client.
この文字列がサーバログのみに渡り、クライアントに渡らない点を除きerrdetail_log(const char *msg, ...)はerrdetailと同一です。
errdetail（や上記の等価物の１つ）とerrdetail_logが共に使用された場合、１つの文字列はクライアントに渡り、もう１つはログに渡ります。
クライアントに送られるレポートに含めるにはセキュリティに対して慎重を期さなければならないもの、あるいは膨大すぎるエラー詳細に対して効果があります。
<function>errdetail_log_plural(const char *fmt_singular, const char
*fmt_plural, unsigned long n, ...)</function> is like
<function>errdetail_log</function>, but with support for various plural forms of
the message.
For more information see <xref linkend="nls-guidelines"/>.
errdetail_log_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n, ...)はerrdetail_logと似ていますが、メッセージの各種の複数書式をサポートします。
より詳細な情報は55.2.2を参照してください。
<function>errhint(const char *msg, ...)</function> supplies an optional
<quote>hint</quote> message; this is to be used when offering suggestions
about how to fix the problem, as opposed to factual details about
what went wrong.
The message string is processed in just the same way as for
<function>errmsg</function>.
errhint(const char *msg, ...)は、省略可能な「ヒント」メッセージを提供します。
これは、何が悪かったのかについての事実に基づく詳細とは反対で、問題を解決させる方法に関する提言を提供するために使用されます。
このメッセージ文字列はerrmsgとまったく同じ方法で処理されます。
<function>errhint_plural(const char *fmt_singular, const char *fmt_plural,
unsigned long n, ...)</function> is like <function>errhint</function>, but with
support for various plural forms of the message.
For more information see <xref linkend="nls-guidelines"/>.
errhint_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n, ...)はerrhintと似ていますが、メッセージの各種の複数書式をサポートします。
より詳細な情報は55.2.2を参照してください。
<function>errcontext(const char *msg, ...)</function> is not normally called
directly from an <function>ereport</function> message site; rather it is used
in <literal>error_context_stack</literal> callback functions to provide
information about the context in which an error occurred, such as the
current location in a PL function.
The message string is processed in just the same way as for
<function>errmsg</function>. Unlike the other auxiliary functions, this can
be called more than once per <function>ereport</function> call; the successive
strings thus supplied are concatenated with separating newlines.
errcontext(const char *msg, ...)は通常ereportメッセージ側から直接呼び出されません。
エラーが発生したコンテキスト、例えばPL関数の現在位置の情報を提供するためにerror_context_stackコールバック関数内で使用されます。
メッセージ文字列はerrmsgとまったく同じ方法で処理されます。
他の補助関数とは異なり、1つのereport呼び出しで何度も呼び出すことができます。
こうして提供される文字列の並びは、改行で区切った形で連結されます。
<function>errposition(int cursorpos)</function> specifies the textual location
of an error within a query string. Currently it is only useful for
errors detected in the lexical and syntactic analysis phases of
query processing.
errposition(int cursorpos)は、問い合わせ文字列内でエラーが発生した位置をテキストで指定します。
現在、問い合わせ処理の字句解析および構文解析段階でエラーが検出された場合にのみ役に立ちます。
<function>errtable(Relation rel)</function> specifies a relation whose
name and schema name should be included as auxiliary fields in the error
report.
errtable(Relation rel)はエラーレポートにおいて名前とスキーマ名が外部フィールドとして含まれなければならないリレーションを指定します。
<function>errtablecol(Relation rel, int attnum)</function> specifies
a column whose name, table name, and schema name should be included as
auxiliary fields in the error report.
errtablecol(Relation rel, int attnum)はエラーレポートにおいて名前、テーブル名、およびスキーマ名が外部フィールドとして含まれなければならない列を指定します。
<function>errtableconstraint(Relation rel, const char *conname)</function>
specifies a table constraint whose name, table name, and schema name
should be included as auxiliary fields in the error report. Indexes
should be considered to be constraints for this purpose, whether or
not they have an associated <structname>pg_constraint</structname> entry. Be
careful to pass the underlying heap relation, not the index itself, as
<literal>rel</literal>.
errtableconstraint(Relation rel, const char *conname)はエラーレポートにおいて名前、テーブル名、およびスキーマ名が外部フィールドとして含まれなければならないテーブル制約を指定します。
この目的のため、関連したpg_constraintエントリの有る無しに関わらず、インデックスは制約と見なされなければなりません。進行中のヒープリレーションを受け渡すにはインデックスではなくrelとすることに注意してください。
<function>errdatatype(Oid datatypeOid)</function> specifies a data
type whose name and schema name should be included as auxiliary fields
in the error report.
errdatatype(Oid datatypeOid)はエラーレポートにおいて名前とスキーマ名が外部フィールドとして含まれなければならないデータ型を指定します。
<function>errdomainconstraint(Oid datatypeOid, const char *conname)</function>
specifies a domain constraint whose name, domain name, and schema name
should be included as auxiliary fields in the error report.
errdomainconstraint(Oid datatypeOid, const char *conname)はエラーレポートにおいて名前、ドメイン名、およびスキーマ名が外部フィールドとして含まれなければならないドメイン制約を指定します。
<function>errcode_for_file_access()</function> is a convenience function that
selects an appropriate SQLSTATE error identifier for a failure in a
file-access-related system call. It uses the saved
<literal>errno</literal> to determine which error code to generate.
Usually this should be used in combination with <literal>%m</literal> in the
primary error message text.
errcode_for_file_access()は、ファイルアクセス関連のシステムコールでの失敗用のSQLSTATEエラー識別子を適切に選択する、便利な関数です。
保存されたerrnoを使用して、どのエラーコードを生成するかを決定します。
通常、これは主エラーメッセージテキスト内で%mと組み合わせて使用されなければなりません。
<function>errcode_for_socket_access()</function> is a convenience function that
selects an appropriate SQLSTATE error identifier for a failure in a
socket-related system call.
errcode_for_socket_access()は、ソケット関連のシステムコールでの失敗用のSQLSTATEエラー識別子を適切に選択する、便利な関数です。
<function>errhidestmt(bool hide_stmt)</function> can be called to specify
suppression of the <literal>STATEMENT:</literal> portion of a message in the
postmaster log. Generally this is appropriate if the message text
includes the current statement already.
errhidestmt(bool hide_stmt)は、postmasterのログ内のメッセージにおけるSTATEMENT:部分を抑制するために呼び出すことができます。
通常これは、メッセージテキスト内にすでに現在の文が含まれている場合に適しています。
<function>errhidecontext(bool hide_ctx)</function> can be called to
specify suppression of the <literal>CONTEXT:</literal> portion of a message in
the postmaster log. This should only be used for verbose debugging
messages where the repeated inclusion of context would bloat the log
too much.
errhidecontext(bool hide_ctx)は、postmasterのログ内のメッセージにおけるCONTEXT:部分を抑制するために呼び出すことができます。
これは、冗長なデバッグメッセージにおいてコンテキストを繰り返し含めることがログのサイズを巨大にしてしまうような場合にのみ用いられるべきです。
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"/>. 54.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)を明示的に記述したとしても正確なものにはなりません。
したがって、このようにはしないでください。