5. バグレポートガイドライン

<title>Bug Reporting Guidelines</title>

When you find a bug in <productname>PostgreSQL</productname> we want to hear about it. Your bug reports play an important part in making <productname>PostgreSQL</productname> more reliable because even the utmost care cannot guarantee that every part of <productname>PostgreSQL</productname> will work on every platform under every circumstance. PostgreSQLに関してバグを発見した場合、ぜひ我々に連絡してください。 最大限の注意を払っても、全てのプラットフォーム、全ての環境でPostgreSQLの機能全てが正常に動くことは保証できませんので、バグレポートはPostgreSQLをより信頼性の高いものにするために、大変重要になります。

The following suggestions are intended to assist you in forming bug reports that can be handled in an effective fashion. No one is required to follow them but doing so tends to be to everyone's advantage. 下記の助言は、有効に活用され得るバグレポートを作成する際に、作成者を支援することを狙ったものです。 これに従う義務はありませんが、沿った方がより有益なものとなるでしょう。

We cannot promise to fix every bug right away. If the bug is obvious, critical, or affects a lot of users, chances are good that someone will look into it. It could also happen that we tell you to update to a newer version to see if the bug happens there. Or we might decide that the bug cannot be fixed before some major rewrite we might be planning is done. Or perhaps it is simply too hard and there are more important things on the agenda. If you need help immediately, consider obtaining a commercial support contract. 私たちは、すべてのバグを直ちに修正することを約束することはできません。 そのバグが明確で、重大で、あるいは他の多くのユーザにも影響を与えるものであれば、誰かがすぐに調査する可能性が高くなるでしょう。 また、より新しいバージョンに変えて、そこでも同じようなことが起こるかを確認してもらうように伝える場合もあります。 あるいは、現在計画中の大きな変更が終了するまで、バグを修正できないと判断する場合もあります。 また、単に修正が非常に困難であり、より重要な他の事項があることもあります。 早急に処置が必要な場合は、商用サポートの購入を検討してください。

5.1. バグの特定

<title>Identifying Bugs</title>

Before you report a bug, please read and re-read the documentation to verify that you can really do whatever it is you are trying. If it is not clear from the documentation whether you can do something or not, please report that too; it is a bug in the documentation. If it turns out that a program does something different from what the documentation says, that is a bug. That might include, but is not limited to, the following circumstances: バグ報告を行う前に、ドキュメントを読み、もう一度読み返し、実行しようとしている処理が実行可能かどうか確認してください。 実行可能かどうかが不明な場合は、その旨を報告してください。 それはドキュメントのバグです。 また、ドキュメントに書かれていることと実際の結果が異なる場合にはバグとなります。 以下のような状況が考えられます。 但し、これらに限定しているわけではありません。

  • A program terminates with a fatal signal or an operating system error message that would point to a problem in the program. (A counterexample might be a <quote>disk full</quote> message, since you have to fix that yourself.) プログラムが致命的なシグナル、またはオペレーティングシステムのエラーメッセージで終了し、それがプログラム内部の問題を指摘している場合。 (逆に、disk fullのようなメッセージはプログラムの問題ではありませんから、この場合は自分で修正してください。)

  • A program produces the wrong output for any given input. あるプログラムで、入力された値に対して間違った結果を返す場合。

  • A program refuses to accept valid input (as defined in the documentation). (ドキュメントで定義されている)有効な値を入力してもプログラムで受け付けない場合。

  • A program accepts invalid input without a notice or error message. But keep in mind that your idea of invalid input might be our idea of an extension or compatibility with traditional practice. プログラムが、無効な入力値を通知やエラーメッセージなどを表示せずに受け入れる場合。 但し、無効な入力と思われるものでも、拡張、あるいは過去の経緯による互換性と考えられている可能性があることに注意してください。

  • <productname>PostgreSQL</productname> fails to compile, build, or install according to the instructions on supported platforms. サポートされているプラットフォームで、PostgreSQLが手順通りにコンパイル、ビルド、インストールできない場合。

Here <quote>program</quote> refers to any executable, not only the backend process. ここでは、プログラムとはバックエンドプロセスだけではなく、すべての実行可能ファイルを意味します。

Being slow or resource-hogging is not necessarily a bug. Read the documentation or ask on one of the mailing lists for help in tuning your applications. Failing to comply to the <acronym>SQL</acronym> standard is not necessarily a bug either, unless compliance for the specific feature is explicitly claimed. プログラムの実行が遅かったり、リソースを大量に使用するのは必ずしもバグではありません。 アプリケーションを改善するためには、ドキュメントを読んだり、どこかのメーリングリストで尋ねてみたりしてください。 標準SQLの要求に応じない場合も、その機能の互換性を明確にうたっていない限り、バグとは言えません。

Before you continue, check on the TODO list and in the FAQ to see if your bug is already known. If you cannot decode the information on the TODO list, report your problem. The least we can do is make the TODO list clearer. 以降に進む前に、TODOリストやFAQを参照して、そのバグが既知のものかどうか確認してください。 もしTODOリストの情報を読み取ることができなければ、問題を報告してください。 少なくともTODOリストを分かりやすくすることができます。

5.2. 報告すべきこと

<title>What to Report</title>

The most important thing to remember about bug reporting is to state all the facts and only facts. Do not speculate what you think went wrong, what <quote>it seemed to do</quote>, or which part of the program has a fault. If you are not familiar with the implementation you would probably guess wrong and not help us a bit. And even if you are, educated explanations are a great supplement to but no substitute for facts. If we are going to fix the bug we still have to see it happen for ourselves first. Reporting the bare facts is relatively straightforward (you can probably copy and paste them from the screen) but all too often important details are left out because someone thought it does not matter or the report would be understood anyway. バグ報告で最も重要なことは、全ての事実を、そして事実のみを明確に記述することです。 何が起こったのか、または、プログラムのどこが問題か、何々が起こっているようだなどの憶測や推測を記述しないでください。 実装にさほど詳しくない方の推測は正しくない場合があり、有効なバグ報告になりません。 実装に精通している方の場合であっても、根拠のある説明は参考情報となりますが、やはり正しい事実が一番役に立ちます。 バグを修正するためには、まず開発者自身がそのバグを再現する必要があります。 ありのままの事実を報告することは、単刀直入(多くの場合は画面からメッセージをコピー&ペーストを行うのみ)ですが、えてして、重要でないだろうと想像したり、省いても理解してもらえるだろうという思い込みによって、重要な情報が洩れてしまう場合がかなり多くあります。

The following items should be contained in every bug report: 全てのバグ報告では、下記の内容が記述されていなければいけません。

  • The exact sequence of steps <emphasis>from program start-up</emphasis> necessary to reproduce the problem. This should be self-contained; it is not enough to send in a bare <command>SELECT</command> statement without the preceding <command>CREATE TABLE</command> and <command>INSERT</command> statements, if the output should depend on the data in the tables. We do not have the time to reverse-engineer your database schema, and if we are supposed to make up our own data we would probably miss the problem. 問題を再現できるように、プログラムの起動から行った作業を順序通りに記述してください。 例えば、出力がテーブルのデータに依存するならば、単にSELECT文を記述していても、それ以前に行われた、CREATE TABLEINSERT文が記述されていなければ十分とはいえません。 我々は、ユーザのデータベーススキーマをリバースエンジニアリングするための時間を取ることができませんし、推測してデータを構築したとしても、おそらく間違えることになるでしょう。

    The best format for a test case for SQL-related problems is a file that can be run through the <application>psql</application> frontend that shows the problem. (Be sure to not have anything in your <filename>~/.psqlrc</filename> start-up file.) An easy way to create this file is to use <application>pg_dump</application> to dump out the table declarations and data needed to set the scene, then add the problem query. You are encouraged to minimize the size of your example, but this is not absolutely necessary. If the bug is reproducible, we will find it either way. SQL関連の問題のテストケースの最適な書式は、psqlフロントエンドに直接読み込ませて問題を再現することができるファイルを用意することです (~/.psqlrcの起動ファイルに何も書かれていないことを確認してください)。 このファイルを簡単に作成するには、pg_dumpを使ってテーブル定義とその状況を再現させるために必要なデータを取り出し、問題の起こった問い合わせを追加します。 サンプルデータの量を減らすことは、推奨されますが必ずしも必要ではありません。 どのような方法であれ、バグが再現できればよいのです。

    If your application uses some other client interface, such as <application>PHP</>, then please try to isolate the offending queries. We will probably not set up a web server to reproduce your problem. In any case remember to provide the exact input files; do not guess that the problem happens for <quote>large files</quote> or <quote>midsize databases</quote>, etc. since this information is too inexact to be of use. アプリケーションがPHPなど何か別のクライアントインタフェースを使用している場合、問題となる問い合わせを切り出してください。 問題を再現させるために我々がWebサーバをセットアップすることは、おそらくないでしょう。 どのような場合においても、正確な入力ファイルを提供することを忘れないでください。 大規模ファイル中規模データベースで発生する問題である、といった推測は行わないでください。 こうした情報は不正確過ぎて役に立ちません。

  • The output you got. Please do not say that it <quote>didn't work</quote> or <quote>crashed</quote>. If there is an error message, show it, even if you do not understand it. If the program terminates with an operating system error, say which. If nothing at all happens, say so. Even if the result of your test case is a program crash or otherwise obvious it might not happen on our platform. The easiest thing is to copy the output from the terminal, if possible. 得られた出力そのもの。 うまくいかなかった、あるいはクラッシュしたといった報告はしないでください。 エラーメッセージがあるならば、たとえ意味が理解できなくてもそれを報告してください。 オペレーティングシステムのエラーでプログラムが強制終了してしまったら、どのエラーでそうなったのかを報告してください。 何も起こらない場合も、その旨を報告してください。 たとえテストケースの結果がプログラムのクラッシュなど明確な場合でも、我々のプラットフォームで再現できない場合があります。 最も容易な方法は、出力をターミナルからコピーすることです。

    注記

    If you are reporting an error message, please obtain the most verbose form of the message. In <application>psql</>, say <literal>\set VERBOSITY verbose</> beforehand. If you are extracting the message from the server log, set the run-time parameter <xref linkend="guc-log-error-verbosity"> to <literal>verbose</> so that all details are logged. エラーメッセージを報告する場合、そのメッセージを最大限詳細に取得してください。 psqlでは、前もって\set VERBOSITY verboseを指定してください。 サーバログからメッセージを取り出す場合は、全ての詳細をログに取得できるようにlog_error_verbosity実行時パラメータをverboseに設定してください。

    注記

    In case of fatal errors, the error message reported by the client might not contain all the information available. Please also look at the log output of the database server. If you do not keep your server's log output, this would be a good time to start doing so. 致命的なエラーが起こった場合、クライアント側で報告されるエラーメッセージには得られる情報が全て書かれているとは限りません。 データベースサーバのログも見てみてください。 もしログを取っていないならば、取る習慣を付けるいいタイミングです。

  • The output you expected is very important to state. If you just write <quote>This command gives me that output.</quote> or <quote>This is not what I expected.</quote>, we might run it ourselves, scan the output, and think it looks OK and is exactly what we expected. We should not have to spend the time to decode the exact semantics behind your commands. Especially refrain from merely saying that <quote>This is not what SQL says/Oracle does.</quote> Digging out the correct behavior from <acronym>SQL</acronym> is not a fun undertaking, nor do we all know how all the other relational databases out there behave. (If your problem is a program crash, you can obviously omit this item.) どのような出力を望んでいたのかを記述することも非常に重要です。 ただ単にこのコマンドはこのような出力を返したや、期待していた結果ではないだけでは、再現して結果を検証した際、開発者は、これは期待した通りの正しい結果である、と考えるかもしれません。 送られてきたコマンドの背後にある文脈を全て把握することはできません。 また、特にSQLではこう書かれていない/Oracleではこのようにならないというコメントはご遠慮願います。 SQLの正確な動作を探し出すのは楽しい作業ではありませんし、また、世にある他のリレーショナルデータベースの動作全てをPostgreSQLの開発者が把握しているわけでもありません (問題がプログラムのクラッシュである場合、この内容は言うまでもなく省略できます)。

  • Any command line options and other start-up options, including any relevant environment variables or configuration files that you changed from the default. Again, please provide exact information. If you are using a prepackaged distribution that starts the database server at boot time, you should try to find out how that is done. すべてのコマンドラインオプションと起動時のオプション、デフォルトから変更した関連する環境変数や設定ファイル。 繰り返しますが、正確な情報を提供してください。 OSの起動時にデータベースサーバを起動するようにパッケージされたディストリビューションを使用している場合は、それらがどのように実行されているかを確認する必要があります。

  • Anything you did at all differently from the installation instructions. インストールの手順書から変更して実行したすべての内容。

  • The <productname>PostgreSQL</productname> version. You can run the command <literal>SELECT version();</literal> to find out the version of the server you are connected to. Most executable programs also support a <option>&#045;&#045;version</option> option; at least <literal>postgres &#045;&#045;version</literal> and <literal>psql &#045;&#045;version</literal> should work. If the function or the options do not exist then your version is more than old enough to warrant an upgrade. If you run a prepackaged version, such as RPMs, say so, including any subversion the package might have. If you are talking about a Git snapshot, mention that, including the commit hash. PostgreSQLのバージョン。 SELECT version();で、接続しているサーバのバージョンがわかります。 多くの実行可能なプログラムでは--versionオプションも使用できます。 少なくともpostgres --versionpsql --versionは実行できるはずです。 これらの関数やオプションが使用できない場合、アップグレードが保証されているものよりも、さらに古いバージョンです。 RPMなどパッケージ化されたものを使用している場合は、その旨を連絡し、パッケージに付加されたバージョン番号があれば、それも記載してください。 Git版に対するバグ報告の場合は、その旨も記載し、コミットハッシュの情報も含めてください。

    If your version is older than &version; we will almost certainly tell you to upgrade. There are many bug fixes and improvements in each new release, so it is quite possible that a bug you have encountered in an older release of <productname>PostgreSQL</> has already been fixed. We can only provide limited support for sites using older releases of <productname>PostgreSQL</>; if you require more than we can provide, consider acquiring a commercial support contract. 10.0よりもバージョンが古い場合、アップグレードすることをお勧めします。 新しいリリースでは多くのバグ修正や改良がなされているからです。 ですので、古めのPostgreSQLのリリースを使用していて遭遇した不具合が修正されている可能性がかなりあります。 古いPostgreSQLのリリースを使用しているサイトに対して、我々は限定されたサポートしか提供することができません。 それ以上のサポートが必要であれば、商用サポート契約を結ぶことを検討してください。

  • Platform information. This includes the kernel name and version, C library, processor, memory information, and so on. In most cases it is sufficient to report the vendor and version, but do not assume everyone knows what exactly <quote>Debian</quote> contains or that everyone runs on i386s. If you have installation problems then information about the toolchain on your machine (compiler, <application>make</application>, and so on) is also necessary. プラットフォーム情報。 カーネル名とバージョン、Cライブラリ、プロセッサ、メモリ情報なども含めて報告してください。 多くの場合、ベンダ名とそのバージョンを明記するだけで十分ですが、Debianの正確な構成要素を全ての人間が把握している、であるとか、全ての人間がi386系を使用しているなどの思い込みは止めてください。 インストールに関する問題の場合は、マシンのツール群(コンパイラやmakeなど)の情報も必要となります。

Do not be afraid if your bug report becomes rather lengthy. That is a fact of life. It is better to report everything the first time than us having to squeeze the facts out of you. On the other hand, if your input files are huge, it is fair to ask first whether somebody is interested in looking into it. Here is an <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">article</ulink> that outlines some more tips on reporting bugs. バグ報告が長文になってもそれは仕方がないことなので、気にしないでください。 最初に全ての情報を入手できる方が、開発者が事実を聞き出さなければいけない状況よりも良いです。 その一方、ファイルが大きいならば、その情報に誰か興味があるかを最初に尋ねるのが得策かもしれません。 記事には、バグ報告に関するその他のコツの概要があります。

Do not spend all your time to figure out which changes in the input make the problem go away. This will probably not help solving it. If it turns out that the bug cannot be fixed right away, you will still have time to find and share your work-around. Also, once again, do not waste your time guessing why the bug exists. We will find that out soon enough. 問題を解決する入力を見つけ出すための試行錯誤に時間をかけないでください。 これはおそらく問題解決の助けになりません。 バグが即座に修正されない場合、その時間を利用すれば、あなた自身のワークアラウンドを探して共有することができます。 繰り返しになりますが、バグがなぜあるのかを解明するのに余計な時間をかける必要はありません。 開発者の方が十分速くそれを見つけ出します。

When writing a bug report, please avoid confusing terminology. The software package in total is called <quote>PostgreSQL</quote>, sometimes <quote>Postgres</quote> for short. If you are specifically talking about the backend process, mention that, do not just say <quote>PostgreSQL crashes</quote>. A crash of a single backend process is quite different from crash of the parent <quote>postgres</> process; please don't say <quote>the server crashed</> when you mean a single backend process went down, nor vice versa. Also, client programs such as the interactive frontend <quote><application>psql</application></quote> are completely separate from the backend. Please try to be specific about whether the problem is on the client or server side. バグ報告をする際、理解しやすい用語を使用してください。 このソフトウェアパッケージ全体はPostgreSQLと呼ばれていますが、略してPostgresとも呼ばれます。 特にバックエンドプロセスに関して述べる時は、そのように明記し、PostgreSQLがクラッシュするとは記述しないでください。 1つのバックエンドプロセスのクラッシュと、その親プロセスpostgresのクラッシュとはかなり異なります。 1つのバックエンドがダウンしてしまったことを、サーバがクラッシュしたとは記述しないでください。 その逆の場合にも当てはまります。 また、psql対話式フロントエンドなどのクライアントプログラムはバックエンドとは完全に分離されています。 問題がクライアント側かサーバ側かの切り分けを試みてください。

5.3. バグ報告先

<title>Where to Report Bugs</title>

In general, send bug reports to the bug report mailing list at <email>pgsql-bugs@postgresql.org</email>. You are requested to use a descriptive subject for your email message, perhaps parts of the error message. 一般論として、バグ報告はというバグ報告用メーリングリストに送ってください。 バグ報告の題名には、エラーメッセージの一部分などわかりやすいものを使ってください。

Another method is to fill in the bug report web-form available at the project's <ulink url="https://www.postgresql.org/">web site</ulink>. Entering a bug report this way causes it to be mailed to the <email>pgsql-bugs@postgresql.org</email> mailing list. その他の方法として、プロジェクトのWebサイトにあるバグ報告フォームの項目を埋める方法があります。 この方法で入力したバグ報告は、メーリングリストに送信されます。

If your bug report has security implications and you'd prefer that it not become immediately visible in public archives, don't send it to <literal>pgsql-bugs</literal>. Security issues can be reported privately to <email>security@postgresql.org</email>. バグ報告にセキュリティが関連する場合や公開アーカイブからすぐに閲覧できることを好まない場合、pgsql-bugsには送信しないでください。 セキュリティの問題については、非公開でに報告することができます。

Do not send bug reports to any of the user mailing lists, such as <email>pgsql-sql@postgresql.org</email> or <email>pgsql-general@postgresql.org</email>. These mailing lists are for answering user questions, and their subscribers normally do not wish to receive bug reports. More importantly, they are unlikely to fix them. などのユーザ向けのメーリングリストには決してバグ報告を送らないでください。 これらのメーリングリストはユーザからの質問に答えるためのもので、ほとんどの購読者はバグ報告を受け取りたくないと思われます。 さらに重要なのは、これらのリストの購読者によってバグが修正されることはほとんどないということです。

Also, please do <emphasis>not</emphasis> send reports to the developers' mailing list <email>pgsql-hackers@postgresql.org</email>. This list is for discussing the development of <productname>PostgreSQL</productname>, and it would be nice if we could keep the bug reports separate. We might choose to take up a discussion about your bug report on <literal>pgsql-hackers</literal>, if the problem needs more review. また、開発者向けのにもバグ報告を送らないでください。 ここはPostgreSQLの開発に関して議論する場で、バグ報告とは切り離している方が良いとされています。 もしその問題により多くのレビューが必要な場合は、そのバグ報告をpgsql-hackersで議論することになります。

If you have a problem with the documentation, the best place to report it is the documentation mailing list <email>pgsql-docs@postgresql.org</email>. Please be specific about what part of the documentation you are unhappy with. ドキュメントに関して問題がある場合は、ドキュメント用のメーリングリスト、が最適な報告先です。 その際、問題になった箇所がどの部分かを明記してください。

If your bug is a portability problem on a non-supported platform, send mail to <email>pgsql-hackers@postgresql.org</email>, so we (and you) can work on porting <productname>PostgreSQL</productname> to your platform. また、サポートされていないプラットフォームへの移植に関係するバグ報告である場合はに報告してください。 そのプラットフォームへPostgreSQLを移植するように(報告者と一緒に)最善の努力をします。

注記

Due to the unfortunate amount of spam going around, all of the above email addresses are closed mailing lists. That is, you need to be subscribed to a list to be allowed to post on it. (You need not be subscribed to use the bug-report web form, however.) If you would like to send mail but do not want to receive list traffic, you can subscribe and set your subscription option to <literal>nomail</>. For more information send mail to <email>majordomo@postgresql.org</email> with the single word <literal>help</> in the body of the message. spamメールを防止するために、残念なことに、これらのメーリングリストは非公開となっています。 つまり、これらのメーリングリストに投稿するには、講読していなければいけません (但し、Webフォームによるバグ報告の場合には、メーリングリストを購読している必要はありません)。 メーリングリストからのメールを受け取らずに単にメールを送りたい場合は、購読登録を行い、講読オプションをnomailに設定してください。 詳細な情報については宛に、helpとだけ本文に書いてメールを送ってください。