臭蟲匯報指導 · PostgreSQL 中文文檔 9.3

# 臭蟲匯報指導當你在PostgreSQL里碰到臭蟲時，我們也希望能知道它。你的臭蟲匯報是將PostgreSQL做得更加可靠的一個非常重要的部分，因為再細致的工作也不能保證在任何情況、任何平臺下PostgreSQL 的每一個部分都能正常工作。下面的建議試圖幫助你正確格式化臭蟲報告，這樣這些報告就能夠以一種有效的方法處理。我們不強迫任何人遵循這些東西，但是這樣做對我們每個人都有好處。我們不能保證能夠馬上修補每個臭蟲。如果臭蟲是顯而易見的，很關鍵的或者影響許多用戶，那么很有可能有些人會認真檢查它們。同樣我們也可能是告訴你升級到一個新版本，看看臭蟲是否仍然存在。否則，我們可能會說這個臭蟲在我們正計劃的幾個主要改寫之前不會得到修補。或者這個臭蟲只是太費事了，而且目前的日程表上有更重要的事情要做。如果你立即需要幫助，那么請考慮獲取一個商業性的支持。 ## 標識臭蟲在你報告臭蟲之前，請一再仔細地讀文檔，以確認你確實可以做你在做的事情。如果文檔中對你能否處理你所做的事情并不清楚，也請你匯報過來，因為這個是文檔的臭蟲。如果發現你的程序表現的不像文檔里說的那樣，那就是一個臭蟲。這時可能包括(不過不一定局限于)下面的現像： * 程序帶著一個致命信號或者一個指向程序錯誤的操作系統錯誤信息退出。一個反例是一個"disk full"(磁盤滿)信息，因為這樣的錯誤必須在 Postgres 外部進行修復。 * 程序對給出的任何輸入都產生錯誤的輸出。 * 程序拒絕接收(文檔里定義的那些)有效的輸入。 * 程序對非法輸入沒有生成任何提示或者錯誤信息。但是需要注意的是，你認為非法的輸入可能是我們設想的擴展或者與傳統兼容的做法。 * 在支持的平臺上根據指導未能成功地編譯或安裝PostgreSQL。這里的"程序"代表任何可執行文件，而不僅僅是后端進程。速度慢或者資源消耗大不算是臭蟲。請閱讀文檔或者提交郵件列表獲取調節你的應用的性能的幫助。未能遵循SQL標準也不算是一個臭蟲，除非文檔明確聲明了遵守該特定特性。在你準備繼續匯報臭蟲之前，請檢查 TODO 列表和 FAQ ，看看你報告的臭蟲是否已知。如果你不能解析 TODO 列表里面的信息，請匯報你的問題。至少我們可以把 TODO 列表做得更清晰。 ## 匯報什么關于匯報臭蟲需要記住的最重要的事就是寫出所有事實并且只寫事實。不要推測你認為是什么錯了，什么"看起來像"，或者是推測程序的哪一部分失靈了。如果你不熟悉 PostgreSQL 的實現，你很可能猜錯因而不能幫我們任何忙。而且即使你熟悉 Postgres 的實現，提煉出來的解釋也只是事實的補充而不是代替。如果我們準備修理這個臭蟲，我們仍然需要首先親自看到臭蟲的出現。報告簡單的事實相對而言比較直接 (你可以從屏幕上拷貝和粘貼)，不過經常發生的是很多人認為這些事實不重要而忽略了重要的細節，否則匯報總是能夠被我們理解。下面的條目應該包含在所有臭蟲匯報里面： * _從程序啟動開始_到重現問題的準確步驟順序。這應該自包含的；要知道如果輸出將依賴于表中的數據時，光把一個光禿禿的`SELECT` 語句發過來而不把前面的`CREATE TABLE`和`INSERT` 語句發過來是不夠的。我們沒有時間分析你的數據庫結構，而且如果我們試著建立我們自己的數據，那我們就有可能錯過問題。測試與 SQL 語言有關的問題的最好的格式是一個可以通過psql 前端運行并顯示問題的文件(確保在`~/.psqlrc`啟動文件里面沒有任何東西)。一種比較簡單的創建這個文件的方法就是用pg_dump 導出表聲明和仿真的數據，以及有毛病的查詢。我們鼓勵你最小化你的例子，但這不是非做不可的事情。如果臭蟲是可以復現的，那么兩種方式都能幫助我們找到它。如果你的應用使用其它客戶端接口，比如PHP，那么請設法隔離出有毛病的查詢。我們可能不會架設一個 web 服務器來復現你的問題。不管怎么說，請記住提供準確的輸入文件，而不要猜測問題會在"大文件"或者"中等尺寸的數據庫"等等的身上發生。因為這樣的信息太不確切，因而沒有什么用處。 * 你得到的輸出。請不要說它"不起作用"或者"失靈了"。如果有錯誤信息，請寫明，即使你不能理解也一樣。如果程序帶著操作系統錯誤退出，也請寫清楚。如果什么也沒有發生，就照直說。即使你的測試實例是程序崩潰或者其它顯而易見的現像，它也有可能不會在我們的平臺上發生。如果可能，最簡單的事情是從終端拷貝輸出。 > **Note:** 如果你報告一個錯誤信息，請從信息中獲取最冗長的版本。在psql里，事先運行`\set VERBOSITY verbose`就行。如果你從服務器日志里抽取信息，那么就把運行時參數[log_error_verbosity](#calibre_link-1335)設置為`verbose`，這樣就會報告所有細節。 > **Note:** 如果是致命錯誤，客戶端提供的信息可能不會包含所有能得到的信息。這種情況下，還要看看數據庫服務器的輸出。如果你沒有保留服務器輸出，那么現在是做這件事的好機會。 * 還有一樣很重要的事是聲明你期望的輸出。如果你只是寫到"這條命令給我這樣的輸出" 或者"這不是我期望的"，我們可能自己運行它，檢查輸出，然后認為看上去很好并且正是我們所期望的輸出。我們不應該把時間花在解析你的命令的語義上。特別是要避免僅僅說"這不是 SQL 說的"或"這不像 Oracle 做的那樣"。從SQL里挖掘出正確的行為可不是好玩的事情，我們也不能知道所有其它的關系數據庫的特性是怎樣的。如果你的問題是程序崩潰，顯然你可以忽略這個條目。 * 任何命令行選項和其它啟動選項，包括相關的環境變量或者你從缺省值修改以后的配置文件。同時，還要準確。如果你使用啟動系統時自動啟動數據庫服務器的預打包的版本，你應該試著找出這些東西是怎樣實現的。 * 任何你做的與安裝指導不一致的東西。 * PostgreSQL 版本。你可以運行`SELECT version();` 命令來檢查你正在運行的版本是什么。大多數可執行程序支持`--version`選項；至少`postgres --version`和`psql --version`應該是可以用的。如果這個函數或者選項不存在，那我們很可能除了告訴你升級外不會說別的東西。如果你運行預打包的版本(例如 RPM)，請說明，包括那個包可能有的任何子版本號。如果你說的是 Git 快照，也請說明，包括提交hash。如果你的版本比9.3.1低，我們幾乎肯定要告訴你升級。在每個新版本里都修補了大量的臭蟲，所以你在老版本的PostgreSQL里碰到的毛病很有可能已經修復掉了。我們只能對那些使用老版本的PostgreSQL節點提供有限的支持；如果你要求的比我們能提供的更多，那么考慮一下商業的合同支持。 * 平臺信息。這包括內核名稱和版本、C 庫、處理器、存儲器信息。大多數情況下只需要匯報供應商和版本，但是不要指望每個人都很清楚"Debian" 包括什么東西或者說每個人都運行在i386s上。如果你安裝有問題，那么還要詳細匯報你機器上的工具的信息(編譯器和 make等)。不要怕你的臭蟲匯報太長，這就是生活。一開始就匯報所有的事情要比讓我們從你那里擠出事實要好。另外，如果你的輸入文件非常巨大，先問問有沒有人有興趣查看它也是合理的。這里有一篇 [文章](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html)，概述了一些匯報臭蟲的更多的提示。不要把時間花在尋找如何通過修改輸入來消除問題的方法上。這樣很可能不會對解決問題有任何幫助。如果發現不能直接修理臭蟲，你還有時間來查找和共享你的繞過方法。還有，我們再說一次，不要在猜測臭蟲的位置上面浪費時間。我們能夠及時找到錯誤。在你書寫臭蟲匯報時，請選用不易混淆的術語。軟件包本身被稱為"PostgreSQL"，有時簡稱為"Postgres"。當你特指后端服務器進程時，請明確說明，而不要僅僅是說"PostgreSQL 崩潰了"。一個獨立后端服務器進程的崩潰和父進程 "postgres"崩潰是相當不同的；如果你是說獨立后端進程崩潰了，那么請不要說"服務器崩潰了"，反之亦然。同樣，客戶端程序，比如交互式前端"psql" 是和后端完全獨立的。請試圖說明清楚問題是出現在客戶端還是服務器端。 ## 到哪里匯報臭蟲通常，把匯報發到臭蟲匯報郵件列表`<[pgsql-bugs@postgresql.org](mailto:pgsql-bugs@postgresql.org)>`。我們要求你為電子郵件消息選用一個描述性的題目，也許就用錯誤信息的一部分。另外一個方法是填充 web 表單形式的臭蟲報告，你可以在項目的 [web 站點](http://www.postgresql.org/)找到。用這種方法輸入一個臭蟲報告會導致它被發送到`<[pgsql-bugs@postgresql.org](mailto:pgsql-bugs@postgresql.org)>`郵件列表。如果你的臭蟲報告隱含帶有安全問題，而你不想它立即出現在公開的檔案庫里，那么就不要發送到`pgsql-bugs`。安全問題可以私下里報告到 `<[security@postgresql.org](mailto:security@postgresql.org)>`。不要把臭蟲匯報發送到任何用戶郵件列表里，例如 SQL 語言郵件列表`<[pgsql-sql@postgresql.org](mailto:pgsql-sql@postgresql.org)>` 或`<[pgsql-general@postgresql.org](mailto:pgsql-general@postgresql.org)>`。這些郵件列表用于回答用戶問題，而且那些訂閱者通常不希望接收臭蟲匯報。更重要的是，他們很可能不會修理這些臭蟲。還有，請_不要_向開發者郵件列表`<[pgsql-hackers@postgresql.org](mailto:pgsql-hackers@postgresql.org)>` 發送臭蟲匯報。這個列表用于討論PostgreSQL的開發，因而我們很希望能和臭蟲匯報分離開。如果修理某個毛病需要更多評論，我們可能會在這個`pgsql-hackers`列表開一個關于你的臭蟲的討論會。如果你覺得文檔有問題，請發電子郵件到文檔郵件列表`<[pgsql-docs@postgresql.org](mailto:pgsql-docs@postgresql.org)>`，在你的問題匯報里面指明你認為哪部分有錯誤。如果你的臭蟲是一個在不支持平臺上的移植性問題，向移植性問題郵件列表`<[pgsql-hackers@postgresql.org](mailto:pgsql-hackers@postgresql.org)>`發送電子郵件，這樣我們(還有你)可以一起嘗試把PostgreSQL移植到你的平臺上。 > **Note:** 由于我們不愿意看到各種各樣的垃圾郵件，上面的所有電子郵件地址都是封閉的郵件地址。也就是說，你需要先申請，然后才能發帖子(用 web 表單提交臭蟲報告用不著申請)。如果你只是想發送郵件而不想接受列表的往來郵件，你可以提交郵件并且把提交選項設置為 `nomail`。如果需要更多的信息，你可以向`<[majordomo@postgresql.org](mailto:majordomo@postgresql.org)>` 發送一封郵件，郵件的正文只有一個單詞`help`就可以了。