当您在 PostgreSQL 中发现 bug 时,我们希望收到您的报告。您的 bug 报告对于使 PostgreSQL 更加可靠起着重要作用,因为即使是最谨慎的措施也无法保证 PostgreSQL 的每个部分在每个平台上的每种情况下都能正常工作。
以下建议旨在帮助您撰写能够有效处理的 bug 报告。没有人必须遵循这些建议,但这样做通常对每个人都有好处。
我们不能保证立即修复每个 bug。如果该 bug 很明显、很关键或影响到许多用户,那么很可能会有人调查它。也可能发生我们告诉您更新到较新版本以查看该 bug 是否仍然存在。或者我们可能会决定在完成我们可能正在计划的重大重写之前无法修复该 bug。或者它可能只是太难了,而且议程上有更重要的事情。如果您需要立即帮助,请考虑获得商业支持合同。
在您报告 bug 之前,请阅读并重新阅读文档,以验证您确实可以执行您尝试执行的操作。如果文档中不清楚您是否可以执行某些操作,也请报告这一点;这是文档中的 bug。如果事实证明某个程序执行的操作与文档所说的不同,那就是 bug。这可能包括但不限于以下情况
程序因致命信号或操作系统错误消息而终止,这会指出程序中的问题。(一个反例可能是“磁盘已满”消息,因为您必须自己解决这个问题。)
程序对任何给定的输入产生错误的输出。
程序拒绝接受有效的输入(如文档中所定义)。
程序接受无效的输入,但没有通知或错误消息。但请记住,您对无效输入的理解可能就是我们对扩展或与传统实践兼容的理解。
PostgreSQL 未能按照受支持平台上的说明进行编译、构建或安装。
这里,“程序”指的是任何可执行文件,而不仅仅是后端进程。
速度慢或资源占用过多不一定是 bug。请阅读文档或在邮件列表中寻求有关调整应用程序的帮助。未能遵守SQL标准也不一定是 bug,除非明确声明对特定功能符合性。
在您继续之前,请查看 TODO 列表和 FAQ,看看您的 bug 是否已知。如果您无法解码 TODO 列表上的信息,请报告您的问题。我们至少可以做的是使 TODO 列表更清晰。
关于 bug 报告最重要的事情是陈述所有事实,并且只陈述事实。不要推测您认为哪里出了问题,“它似乎做了什么”,或者程序的哪个部分有故障。如果您不熟悉实现,您可能会猜错,并且对我们没有任何帮助。即使您熟悉,有根据的解释是对事实的很好补充,但不能替代事实。如果我们打算修复 bug,我们仍然必须首先看到它发生。报告基本事实相对简单(您可能可以从屏幕上复制并粘贴它们),但通常会遗漏重要的细节,因为有人认为这无关紧要或者报告无论如何都会被理解。
每个 bug 报告都应包含以下项目
重现该问题所需的准确步骤顺序,从程序启动开始。这应该是自包含的;如果输出取决于表中的数据,则仅发送一个裸的 SELECT
语句而没有前面的 CREATE TABLE
和 INSERT
语句是不够的。我们没有时间对您的数据库模式进行逆向工程,如果我们应该创建自己的数据,我们可能会错过问题。
对于与 SQL 相关的问题,测试用例的最佳格式是一个可以通过 psql 前端运行并显示问题的文件。(请确保您的 ~/.psqlrc
启动文件中没有任何内容。)创建此文件的一种简单方法是使用 pg_dump 转储出设置场景所需的表声明和数据,然后添加问题查询。我们鼓励您尽量缩小示例的大小,但这并不是绝对必要的。如果该 bug 可以重现,无论如何我们都会找到它。
如果您的应用程序使用其他客户端接口,例如 PHP,请尝试隔离有问题的查询。我们可能不会设置 Web 服务器来重现您的问题。无论如何,请记住提供确切的输入文件;不要猜测问题发生在“大文件”或“中等大小的数据库”等情况下,因为此信息太不准确,无法使用。
您得到的输出。请不要说它“不起作用”或“崩溃了”。如果有错误消息,请显示它,即使您不理解它。如果程序因操作系统错误而终止,请说明是哪个错误。如果什么都没发生,请说明。即使您的测试用例的结果是程序崩溃或以其他方式很明显,它也可能不会在我们的平台上发生。最简单的方法是尽可能地从终端复制输出。
如果您报告错误消息,请获取该消息的最详细形式。在 psql 中,请事先说 \set VERBOSITY verbose
。如果您从服务器日志中提取消息,请将运行时参数 log_error_verbosity 设置为 verbose
,以便记录所有详细信息。
在发生致命错误的情况下,客户端报告的错误消息可能不包含所有可用信息。另请查看数据库服务器的日志输出。如果您不保留服务器的日志输出,那么现在是开始这样做的好时机。
您期望的输出非常重要。如果您只是写“此命令给我该输出。”或“这不是我期望的。”,我们可能会自己运行它,扫描输出,并认为它看起来还可以,并且正是我们期望的。我们不应该花时间来解码您命令背后的确切语义。尤其要避免仅仅说“这不是 SQL 所说的/Oracle 所做的。”从SQL中挖掘出正确的行为并不是一件有趣的事情,而且我们也不是所有人都知道其他所有关系数据库的行为方式。(如果你的问题是程序崩溃,你显然可以省略此项。)
任何命令行选项和其他启动选项,包括您从默认值更改的任何相关的环境变量或配置文件。再次,请提供确切的信息。如果您使用的是在启动时启动数据库服务器的预打包分发版,您应该尝试找出是如何完成的。
您在安装说明中有任何不同的操作。
您使用的 PostgreSQL 版本。您可以运行命令 SELECT version();
来查找您连接的服务器的版本。大多数可执行程序也支持 --version
选项;至少 postgres --version
和 psql --version
应该可以工作。如果该函数或选项不存在,则说明您的版本过于老旧,需要升级。如果您运行的是预打包版本,例如 RPM,请说明,包括该软件包可能包含的任何子版本。如果您使用的是 Git 快照,请提及,包括提交哈希值。
如果您的版本低于 17.2,我们几乎肯定会建议您升级。每个新版本都有许多错误修复和改进,因此您在较旧版本的 PostgreSQL 中遇到的错误很可能已经修复。我们只能为使用旧版本 PostgreSQL 的站点提供有限的支持;如果您需要超出我们所能提供的支持,请考虑购买商业支持合同。
平台信息。这包括内核名称和版本、C 库、处理器、内存信息等等。在大多数情况下,报告供应商和版本就足够了,但不要认为每个人都知道 “Debian” 到底包含什么,或者每个人都在 x86_64 上运行。如果您遇到安装问题,那么有关您机器上的工具链(编译器、make 等)的信息也是必要的。
如果您的错误报告变得相当冗长,请不要害怕。这是客观事实。最好第一次就报告所有信息,而不是让我们从您那里挤出事实。另一方面,如果您的输入文件非常大,那么先询问是否有人有兴趣查看它是合理的。这里有一篇文章,概述了更多关于报告错误的技巧。
不要花费所有时间来弄清楚输入中的哪些更改会导致问题消失。这可能无助于解决问题。如果发现该错误无法立即修复,您仍然有时间查找并分享您的解决方法。同样,再次强调,不要浪费时间猜测错误存在的原因。我们很快就会找到答案。
在编写错误报告时,请避免使用令人困惑的术语。整个软件包被称为 “PostgreSQL”,有时简称 “Postgres”。如果您专门谈论的是后端进程,请提及,不要只是说 “PostgreSQL 崩溃了”。单个后端进程的崩溃与父进程 “postgres” 的崩溃截然不同;当您指的是单个后端进程崩溃时,请不要说 “服务器崩溃了”,反之亦然。此外,诸如交互式前端 “psql” 等客户端程序与后端完全分离。请尽量明确问题是在客户端还是服务器端。
通常,请将错误报告发送到错误报告邮件列表 <[email protected]>
。您需要为您的电子邮件使用描述性主题,或许是错误消息的一部分。
另一种方法是填写项目网站上提供的错误报告 Web 表单。通过这种方式输入错误报告会将其邮寄到 <[email protected]>
邮件列表。
如果您的错误报告涉及安全问题,并且您不希望它立即在公共存档中可见,请不要将其发送到 pgsql-bugs
。安全问题可以私下报告给 <[email protected]>
。
不要将错误报告发送到任何用户邮件列表,例如 <[email protected]>
或 <[email protected]>
。这些邮件列表用于回答用户问题,其订阅者通常不希望收到错误报告。更重要的是,他们不太可能修复这些错误。
此外,请 不要 将报告发送到开发人员的邮件列表 <[email protected]>
。此列表用于讨论 PostgreSQL 的开发,如果我们可以将错误报告分开,那就太好了。如果问题需要更多审查,我们可能会选择在 pgsql-hackers
上讨论您的错误报告。
如果您对文档有问题,报告它的最佳位置是文档邮件列表 <[email protected]>
。请具体说明您对文档的哪一部分不满意。
如果您的错误是非支持平台上的可移植性问题,请发送邮件至 <[email protected]>
,这样我们(和您)就可以致力于将 PostgreSQL 移植到您的平台。
由于不幸的垃圾邮件数量过多,除非您订阅了以上所有列表,否则所有列表都将受到审核。这意味着电子邮件的传递会有一些延迟。如果您想订阅这些列表,请访问 https://lists.postgresql.org/ 获取说明。
如果您在文档中看到任何不正确、与您使用特定功能的体验不符或需要进一步澄清的内容,请使用此表单报告文档问题。