当您在 PostgreSQL 中发现错误时,我们希望了解相关信息。您的错误报告在提升 PostgreSQL 的可靠性方面发挥着重要作用,因为即使是最谨慎的处理也无法保证 PostgreSQL 的每个部分都能在任何平台上的任何情况下正常工作。
以下建议旨在帮助您形成可以有效处理的错误报告。没有人必须遵循这些建议,但这样做往往对每个人都有利。
我们无法保证立即修复每个错误。如果错误很明显、很严重或影响很多用户,那么很可能有人会调查它。我们还可能会告诉您更新到较新版本,以查看错误是否发生在该版本中。或者我们可能会决定在完成我们可能正在计划的一些重大重写之前无法修复该错误。或者它可能只是太难,并且议程上有更重要的事情。如果您需要立即获得帮助,请考虑获得商业支持合同。
在报告错误之前,请阅读并重新阅读文档,以验证您是否真的可以执行您正在尝试执行的任何操作。如果从文档中无法明确看出您是否可以执行某些操作,请也报告该问题;这是文档中的错误。如果某个程序执行的操作与文档中所述不同,则这是一个错误。这可能包括但不限于以下情况
程序以致命信号或操作系统错误消息终止,该消息将指向程序中的问题。(一个反例可能是 “磁盘已满” 消息,因为您必须自己修复它。)
对于任何给定的输入,程序都会产生错误的输出。
程序拒绝接受有效输入(如文档中所定义)。
程序在没有通知或错误消息的情况下接受无效输入。但请记住,您对无效输入的理解可能是我们对扩展或与传统实践兼容性的理解。
PostgreSQL 无法按照受支持平台上的说明进行编译、构建或安装。
此处 “程序” 指任何可执行文件,而不仅仅是后端进程。
速度慢或占用资源过多不一定是错误。阅读文档或在某个邮件列表中寻求帮助以调整您的应用程序。除非明确声明特定功能的合规性,否则不遵守 SQL 标准也不一定是错误。
在继续之前,请查看 TODO 列表和常见问题解答,看看您的错误是否已知。如果您无法解码 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 版本。您可以运行命令 SELECT version();
以找出您连接到的服务器版本。大多数可执行程序还支持 --version
选项;至少 postgres --version
和 psql --version
应该可以工作。如果该函数或选项不存在,则您的版本已经足够旧,需要升级。如果您运行预打包版本(例如 RPM),请说明,包括该软件包可能具有的任何子版本。如果您正在谈论 Git 快照,请提及它,包括提交哈希。
如果您的版本低于 16.2,我们几乎肯定会告诉您升级。每个新版本都有许多错误修复和改进,因此您在较旧版本的 PostgreSQL 中遇到的错误很可能已经修复。我们只能为使用较旧版本的 PostgreSQL 的站点提供有限的支持;如果您需要超出我们所能提供的支持,请考虑购买商业支持合同。
平台信息。这包括内核名称和版本、C 库、处理器、内存信息等。在大多数情况下,报告供应商和版本就足够了,但不要假设每个人都知道 “Debian” 确切包含什么或每个人都在 x86_64 上运行。如果您有安装问题,则还需要有关机器上的工具链(编译器、make 等)的信息。
如果您的错误报告变得很长,不要害怕。这是生活中的一个事实。第一次报告所有内容总比我们从您那里挤出事实要好。另一方面,如果您的输入文件很大,那么首先询问是否有人有兴趣查看它是公平的。这是一篇文章,其中概述了有关报告错误的更多提示。
不要花费所有时间来找出输入中的哪些更改使问题消失。这可能无助于解决问题。如果事实证明无法立即修复错误,您仍有时间找到并分享您的解决方法。此外,请再次不要浪费时间猜测错误存在的原因。我们很快就会发现这一点。
在编写错误报告时,请避免使用令人困惑的术语。整个软件包称为“PostgreSQL”,有时简称为“Postgres”。如果您特别谈论后端进程,请提及这一点,不要只说“PostgreSQL 崩溃”。单个后端进程的崩溃与父“postgres”进程的崩溃有很大不同;当您表示单个后端进程关闭时,请不要说“服务器崩溃”,反之亦然。此外,诸如交互式前端“psql”之类的客户端程序与后端完全分离。请尝试具体说明问题出在客户端还是服务器端。
一般来说,将错误报告发送到<[email protected]>
处的错误报告邮件列表。要求您为您的电子邮件信息使用描述性主题,可能是错误消息的一部分。
另一种方法是填写项目网站上提供的错误报告网络表单。以这种方式输入错误报告会导致将其邮寄到<[email protected]>
邮件列表。
如果您的错误报告涉及安全问题,并且您希望它不会立即在公共档案中可见,请不要将其发送到pgsql-bugs
。安全问题可以私下报告给<[email protected]>
。
请勿向任何用户邮件列表发送错误报告,例如 <[email protected]>
或 <[email protected]>
。这些邮件列表用于回答用户问题,其订阅者通常不希望收到错误报告。更重要的是,他们不太可能修复这些错误。
此外,请不要向开发者邮件列表 <[email protected]>
发送报告。此列表用于讨论 PostgreSQL 的开发,如果我们能将错误报告分开,那就太好了。如果问题需要更多审查,我们可能会选择在 pgsql-hackers
上讨论您的错误报告。
如果您对文档有问题,报告问题的最佳位置是文档邮件列表 <[email protected]>
。请具体说明您对文档的哪一部分不满意。
如果您的错误是在不受支持的平台上的可移植性问题,请发送邮件至 <[email protected]>
,以便我们(和您)可以致力于将 PostgreSQL 移植到您的平台。
由于大量垃圾邮件,除非您已订阅,否则以上所有列表都将受到审核。这意味着在发送电子邮件之前会有一些延迟。如果您希望订阅这些列表,请访问 https://lists.postgresql.org/ 以获取说明。