★PostgreSQLカンファレンス2024 12月6日開催/チケット販売中★
他のバージョンの文書 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

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

PostgreSQLに関してバグを発見した場合、ぜひ我々に連絡してください。 最大限の注意を払っても、全てのプラットフォーム、全ての環境でPostgreSQLの機能全てが正常に動くことは保証できませんので、バグレポートはPostgreSQLをより信頼性の高いものにするために、大変重要になります。

下記の助言は、有効に活用され得るバグレポートを作成する際に、作成者を支援することを狙ったものです。 これに従う義務はありませんが、沿った方がより有益なものとなるでしょう。

私たちは、すべてのバグを直ちに修正することを約束することはできません。 そのバグが明確で、重大で、あるいは他の多くのユーザにも影響を与えるものであれば、誰かがすぐに調査する可能性が高くなるでしょう。 また、より新しいバージョンに変えて、そこでも同じようなことが起こるかを確認してもらうように伝える場合もあります。 あるいは、現在計画中の大きな変更が終了するまで、バグを修正できないと判断する場合もあります。 また、単に修正が非常に困難であり、より重要な他の事項があることもあります。 早急に処置が必要な場合は、商用サポートの購入を検討してください。

5.1. バグの特定

バグ報告を行う前に、ドキュメントを読み、もう一度読み返し、実行しようとしている処理が実行可能かどうか確認してください。 実行可能かどうかが不明な場合は、その旨を報告してください。 それはドキュメントのバグです。 また、ドキュメントに書かれていることと実際の結果が異なる場合にはバグとなります。 以下のような状況が考えられます。 但し、これらに限定しているわけではありません。

  • プログラムが致命的なシグナル、またはオペレーティングシステムのエラーメッセージで終了し、それがプログラム内部の問題を指摘している場合。 (逆に、disk fullのようなメッセージはプログラムの問題ではありませんから、この場合は自分で修正してください。)

  • あるプログラムで、入力された値に対して間違った結果を返す場合。

  • (ドキュメントで定義されている)有効な値を入力してもプログラムで受け付けない場合。

  • プログラムが、無効な入力値を通知やエラーメッセージなどを表示せずに受け入れる場合。 但し、無効な入力と思われるものでも、拡張、あるいは過去の経緯による互換性と考えられている可能性があることに注意してください。

  • サポートされているプラットフォームで、PostgreSQLが手順通りにコンパイル、ビルド、インストールできない場合。

ここでは、プログラムとはバックエンドプロセスだけではなく、すべての実行可能ファイルを意味します。

プログラムの実行が遅かったり、リソースを大量に使用するのは必ずしもバグではありません。 アプリケーションを改善するためには、ドキュメントを読んだり、どこかのメーリングリストで尋ねてみたりしてください。 標準SQLの要求に応じない場合も、その機能の互換性を明確にうたっていない限り、バグとは言えません。

以降に進む前に、TODOリストやFAQを参照して、そのバグが既知のものかどうか確認してください。 もしTODOリストの情報を読み取ることができなければ、問題を報告してください。 少なくともTODOリストを分かりやすくすることができます。

5.2. 報告すべきこと

バグ報告で最も重要なことは、全ての事実を、そして事実のみを明確に記述することです。 何が起こったのか、または、プログラムのどこが問題か、何々が起こっているようだなどの憶測や推測を記述しないでください。 実装にさほど詳しくない方の推測は正しくない場合があり、有効なバグ報告になりません。 実装に精通している方の場合であっても、根拠のある説明は参考情報となりますが、やはり正しい事実が一番役に立ちます。 バグを修正するためには、まず開発者自身がそのバグを再現する必要があります。 ありのままの事実を報告することは、単刀直入(多くの場合は画面からメッセージをコピー&ペーストを行うのみ)ですが、えてして、重要でないだろうと想像したり、省いても理解してもらえるだろうという思い込みによって、重要な情報が洩れてしまう場合がかなり多くあります。

全てのバグ報告では、下記の内容が記述されていなければいけません。

  • 問題を再現できるように、プログラムの起動から行った作業を順序通りに記述してください。 例えば、出力がテーブルのデータに依存するならば、単にSELECT文を記述していても、それ以前に行われた、CREATE TABLEINSERT文が記述されていなければ十分とはいえません。 我々は、ユーザのデータベーススキーマをリバースエンジニアリングするための時間を取ることができませんし、推測してデータを構築したとしても、おそらく間違えることになるでしょう。

    SQL関連の問題のテストケースの最適な書式は、psqlフロントエンドに直接読み込ませて問題を再現することができるファイルを用意することです (~/.psqlrcの起動ファイルに何も書かれていないことを確認してください)。 このファイルを簡単に作成するには、pg_dumpを使ってテーブル定義とその状況を再現させるために必要なデータを取り出し、問題の起こった問い合わせを追加します。 サンプルデータの量を減らすことは、推奨されますが必ずしも必要ではありません。 どのような方法であれ、バグが再現できればよいのです。

    アプリケーションがPHPなど何か別のクライアントインタフェースを使用している場合、問題となる問い合わせを切り出してください。 問題を再現させるために我々がWebサーバをセットアップすることは、おそらくないでしょう。 どのような場合においても、正確な入力ファイルを提供することを忘れないでください。 大規模ファイル中規模データベースで発生する問題である、といった推測は行わないでください。 こうした情報は不正確過ぎて役に立ちません。

  • 得られた出力そのもの。 うまくいかなかった、あるいはクラッシュしたといった報告はしないでください。 エラーメッセージがあるならば、たとえ意味が理解できなくてもそれを報告してください。 オペレーティングシステムのエラーでプログラムが強制終了してしまったら、どのエラーでそうなったのかを報告してください。 何も起こらない場合も、その旨を報告してください。 たとえテストケースの結果がプログラムのクラッシュなど明確な場合でも、我々のプラットフォームで再現できない場合があります。 最も容易な方法は、出力をターミナルからコピーすることです。

    注記

    エラーメッセージを報告する場合、そのメッセージを最大限詳細に取得してください。 psqlでは、前もって\set VERBOSITY verboseを指定してください。 サーバログからメッセージを取り出す場合は、全ての詳細をログに取得できるようにlog_error_verbosity実行時パラメータをverboseに設定してください。

    注記

    致命的なエラーが起こった場合、クライアント側で報告されるエラーメッセージには得られる情報が全て書かれているとは限りません。 データベースサーバのログも見てみてください。 もしログを取っていないならば、取る習慣を付けるいいタイミングです。

  • どのような出力を望んでいたのかを記述することも非常に重要です。 ただ単にこのコマンドはこのような出力を返したや、期待していた結果ではないだけでは、再現して結果を検証した際、開発者は、これは期待した通りの正しい結果である、と考えるかもしれません。 送られてきたコマンドの背後にある文脈を全て把握することはできません。 また、特にSQLではこう書かれていない/Oracleではこのようにならないというコメントはご遠慮願います。 SQLの正確な動作を探し出すのは楽しい作業ではありませんし、また、世にある他のリレーショナルデータベースの動作全てをPostgreSQLの開発者が把握しているわけでもありません (問題がプログラムのクラッシュである場合、この内容は言うまでもなく省略できます)。

  • すべてのコマンドラインオプションと起動時のオプション、デフォルトから変更した関連する環境変数や設定ファイル。 ここでも、正確な情報を提供してください。 OSの起動時にデータベースサーバを起動するようにパッケージされたディストリビューションを使用している場合は、それらがどのように実行されているかを確認する必要があります。

  • インストールの手順書から変更して実行したすべての内容。

  • PostgreSQLのバージョン。 SELECT version();で、接続しているサーバのバージョンがわかります。 多くの実行可能なプログラムでは--versionオプションも使用できます。 少なくともpostgres --versionpsql --versionは実行できるはずです。 これらの関数やオプションが使用できない場合、アップグレードが保証されているものよりも、さらに古いバージョンです。 RPMなどパッケージ化されたものを使用している場合は、その旨を連絡し、パッケージに付加されたバージョン番号があれば、それも記載してください。 Git版に対するバグ報告の場合は、その旨も記載し、コミットハッシュの情報も含めてください。

    14.5よりもバージョンが古い場合、アップグレードすることをお勧めします。 新しいリリースでは多くのバグ修正や改良がなされているからです。 ですので、古めのPostgreSQLのリリースを使用していて遭遇した不具合が修正されている可能性がかなりあります。 古いPostgreSQLのリリースを使用しているサイトに対して、我々は限定されたサポートしか提供することができません。 それ以上のサポートが必要であれば、商用サポート契約を結ぶことを検討してください。

  • プラットフォーム情報。 カーネル名とバージョン、Cライブラリ、プロセッサ、メモリ情報なども含めて報告してください。 多くの場合、ベンダ名とそのバージョンを明記するだけで十分ですが、Debianの正確な構成要素を全ての人間が把握している、であるとか、全ての人間がx86_64を使用しているなどの思い込みは止めてください。 インストールに関する問題の場合は、マシンのツール群(コンパイラやmakeなど)の情報も必要となります。

バグ報告が長文になってもそれは仕方がないことなので、気にしないでください。 最初に全ての情報を入手できる方が、開発者が事実を聞き出さなければいけない状況よりも良いです。 その一方、ファイルが大きいならば、その情報に誰か興味があるかを最初に尋ねるのが得策かもしれません。 記事には、バグ報告に関するその他のコツの概要があります。

問題を解決する入力を見つけ出すための試行錯誤に時間をかけないでください。 これはおそらく問題解決の助けになりません。 バグが即座に修正されない場合、その時間を利用すれば、あなた自身のワークアラウンドを探して共有することができます。 繰り返しになりますが、バグがなぜあるのかを解明するのに余計な時間をかける必要はありません。 開発者の方が十分速くそれを見つけ出します。

バグ報告をする際、理解しやすい用語を使用してください。 このソフトウェアパッケージ全体はPostgreSQLと呼ばれていますが、略してPostgresとも呼ばれます。 特にバックエンドプロセスに関して述べる時は、そのように明記し、PostgreSQLがクラッシュするとは記述しないでください。 1つのバックエンドプロセスのクラッシュと、その親プロセスpostgresのクラッシュとはかなり異なります。 1つのバックエンドがダウンしてしまったことを、サーバがクラッシュしたとは記述しないでください。 その逆の場合にも当てはまります。 また、psql対話式フロントエンドなどのクライアントプログラムはバックエンドとは完全に分離されています。 問題がクライアント側かサーバ側かの切り分けを試みてください。

5.3. バグ報告先

一般論として、バグ報告はというバグ報告用メーリングリストに送ってください。 バグ報告の題名には、エラーメッセージの一部分などわかりやすいものを使ってください。

その他の方法として、プロジェクトのWebサイトにあるバグ報告フォームの項目を埋める方法があります。 この方法で入力したバグ報告は、メーリングリストに送信されます。

バグ報告にセキュリティが関連する場合や公開アーカイブからすぐに閲覧できることを好まない場合、pgsql-bugsには送信しないでください。 セキュリティの問題については、非公開でに報告することができます。

などのユーザ向けのメーリングリストには決してバグ報告を送らないでください。 これらのメーリングリストはユーザからの質問に答えるためのもので、ほとんどの購読者はバグ報告を受け取りたくないと思われます。 さらに重要なのは、これらのリストの購読者によってバグが修正されることはほとんどないということです。

また、開発者向けのにもバグ報告を送らないでください。 ここはPostgreSQLの開発に関して議論する場で、バグ報告とは切り離している方が良いとされています。 もしその問題により多くのレビューが必要な場合は、そのバグ報告をpgsql-hackersで議論することになります。

ドキュメントに関して問題がある場合は、ドキュメント用のメーリングリスト、が最適な報告先です。 その際、問題になった箇所がどの部分かを明記してください。

また、サポートされていないプラットフォームへの移植に関係するバグ報告である場合はに報告してください。 そのプラットフォームへPostgreSQLを移植するように(報告者と一緒に)最善の努力をします。

注記

嘆かわしい量のスパムメールが出回っているため、これらのメーリングリストは購読しない限りモデレータ付きとなっています。 これはEメールが配送されるのにいくらか遅延があることを意味します。 メーリングリストを購読したい場合には、https://lists.postgresql.org/を訪ねて、その指示に従ってください。