臭虫汇报指导

当你在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设置为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等)。

不要怕你的臭虫汇报太长，这就是生活。一开始就汇报所有的事情要比让我们从你那里挤出事实要好。另外，如果你的输入文件非常巨大，先问问有没有人有兴趣查看它也是合理的。这里有一篇文章，概述了一些汇报臭虫的更多的提示。

不要把时间花在寻找如何通过修改输入来消除问题的方法上。这样很可能不会对解决问题有任何帮助。如果发现不能直接修理臭虫，你还有时间来查找和共享你的绕过方法。还有，我们再说一次，不要在猜测臭虫的位置上面浪费时间。我们能够及时找到错误。

在你书写臭虫汇报时，请选用不易混淆的术语。软件包本身被称为"PostgreSQL"，有时简称为"Postgres"。当你特指后端服务器进程时，请明确说明，而不要仅仅是说"PostgreSQL 崩溃了"。一个独立后端服务器进程的崩溃和父进程 "postgres"崩溃是相当不同的；如果你是说独立后端进程崩溃了，那么请不要说"服务器崩溃了"，反之亦然。同样，客户端程序，比如交互式前端"psql" 是和后端完全独立的。请试图说明清楚问题是出现在客户端还是服务器端。

到哪里汇报臭虫

通常，把汇报发到臭虫汇报邮件列表<[[email protected]](mailto:[email protected])>。我们要求你为电子邮件消息选用一个描述性的题目，也许就用错误信息的一部分。

另外一个方法是填充 web 表单形式的臭虫报告，你可以在项目的 web 站点找到。用这种方法输入一个臭虫报告会导致它被发送到<[[email protected]](mailto:[email protected])>邮件列表。

如果你的臭虫报告隐含带有安全问题，而你不想它立即出现在公开的档案库里，那么就不要发送到pgsql-bugs。安全问题可以私下里报告到 <[[email protected]](mailto:[email protected])>。

不要把臭虫汇报发送到任何用户邮件列表里，例如 SQL 语言邮件列表<[[email protected]](mailto:[email protected])> 或<[[email protected]](mailto:[email protected])>。这些邮件列表用于回答用户问题，而且那些订阅者通常不希望接收臭虫汇报。更重要的是，他们很可能不会修理这些臭虫。

还有，请不要向开发者邮件列表<[[email protected]](mailto:[email protected])> 发送臭虫汇报。这个列表用于讨论PostgreSQL的开发，因而我们很希望能和臭虫汇报分离开。如果修理某个毛病需要更多评论，我们可能会在这个pgsql-hackers列表开一个关于你的臭虫的讨论会。

如果你觉得文档有问题，请发电子邮件到文档邮件列表<[[email protected]](mailto:[email protected])>，在你的问题汇报里面指明你认为哪部分有错误。

如果你的臭虫是一个在不支持平台上的移植性问题，向移植性问题邮件列表<[[email protected]](mailto:[email protected])>发送电子邮件，这样我们(还有你)可以一起尝试把PostgreSQL移植到你的平台上。

Note: 由于我们不愿意看到各种各样的垃圾邮件，上面的所有电子邮件地址都是封闭的邮件地址。也就是说，你需要先申请，然后才能发帖子(用 web 表单提交臭虫报告用不着申请)。如果你只是想发送邮件而不想接受列表的往来邮件，你可以提交邮件并且把提交选项设置为 nomail。如果需要更多的信息，你可以向<[[email protected]](mailto:[email protected])> 发送一封邮件，邮件的正文只有一个单词help就可以了。