PostgreSQL 8.0.0 文書
前のページ | 巻戻し | はじめに | 早送り | 次のページ

# バグレポートガイドライン

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

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

発見されたバグはただちに修正されるとは限りません。 そのバグが明確で、重大で、他の多くのユーザにも影響を与えるものであれば、すぐに修正される可能性が高いでしょう。 また、より新しいバージョンに変えて、そこでも同じようなことが起こるかを確認してもらうようにお勧めする場合もあります。 あるいは、現在計画中の大きな変更が終了するまでバグを修正できないと判断する場合もあります。 また、そのバグ修正はとても難易度が高いもので、後まわしになることも考えられます。 早急に処置が必要な場合は、商用サポートの購入を検討してください。

## バグの特定

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

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

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

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

- 無効な値を入力し、エラーメッセージなどを表示させずにプログラムがその値を受け入れる場合。 しかし、無効な入力と思われているものでも、実際には拡張や伝統的な理由による互換性のために有効としている可能性もありますので注意してください。

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

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

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

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

## 報告すべきこと

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

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

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

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

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

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

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

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

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

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

- インストール手順書からの変更点を全て記述してください。

- PostgreSQLのバージョン。 `SELECT version();`で、接続しているサーバのバージョンが判ります。 多くの実行可能なプログラムでは`--version`オプションも使用できます。 少なくとも`postmaster --version`と`psql --version`は実行できるはずです。 この関数やオプションが使用できない場合は、そのバージョンはとても古いものであり、アップグレードすべきです。 RPMなどの事前にパッケージされたものを使用している場合は、その旨を連絡し、パッケージの副バージョンがもしあれば、それも記載してください。 CVS版に対するバグ報告の場合は、その旨も記載し、その日時も記載してください。

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

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

バグ報告が長文になってもそれは仕方がないことなので、気にしないでください。 一度に全ての情報を入手できる方が、開発者から情報を催促するよりも手間暇がかかりません。 その一方、ファイルが大きいならば、その情報に誰か興味があるかを始めに尋ねるのが得策かもしれません。

問題を解決させる入力を見つけ出すための試行錯誤に時間をかけないでください。 これはおそらく問題解決の助けになりません。 バグが即座に修正されない場合、その間を利用して様々と試してみてください。 繰返しになりますが、バグがなぜあるのかを解明するのに余計な時間を取る必要はありません。 開発者の方が十分速くそれを見つけ出します。

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

## バグ報告先

一般的には、`<pgsql-bugs@postgresql.org>`というバグ報告用メーリングリストにバグ報告を送ってください。 バグ報告の題名には、エラーメッセージの一部分などわかりやすいものを使ってください。

他に、プロジェクトのwebサイトhttp://www.postgresql.org/にあるバグ報告フォームの項目を埋める方法があります。 この方法で入力したバグ報告は、`<pgsql-bugs@postgresql.org>`メーリングリストに送信されます。

`<pgsql-sql@postgresql.org>`や`<pgsql-general@postgresql.org>`などのユーザ向けのメーリングリストには決してバグ報告を送らないでください。 これらのメーリングリストはユーザからの質問に応えるためのもので、ほとんどの購読者はバグ報告を受け取りたくないと思われます。 もっと重要な点は、この購読者によってバグが修正されることはほとんどありません。

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

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

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

> 注意: spamメールを防止するために、残念なことに、これらのメーリングリストは非公開となっています。 つまり、これらのメーリングリストに投稿するには、講読しなければいけません。 (しかし、webフォームによるバグ報告の場合は購読する必要はありません。) メーリングリストからのメールを受け取らずに単にメールを送りたい場合は、購読登録を行ない、講読オプションを`nomail`に設定してください。 より詳細については`<majordomo@postgresql.org>`宛に、`help`とだけ本文に書いてメールを送ってください。

前のページ | ホーム | 次のページ
より進んだ情報 | 上に戻る | チュートリアル