PostgreSQL 18 中文参考文档(未翻译部分保留英文)🌐 切换到英文原版 →

5. Bug 报告指南 #

5.1. 识别 Bug
5.2. 应报告哪些内容
5.3. 向何处报告 Bug

当你在 PostgreSQL 中发现缺陷(Bug)时,我们非常希望了解相关情况。你的缺陷报告对提升 PostgreSQL 的稳定性与可靠性至关重要,因为即使经过极其严谨的测试,也无法保证系统的每个模块在所有平台和各类复杂运行环境下都能完美工作。

以下建议旨在帮助你撰写便于开发团队高效定位和处理的高质量 Bug 报告。虽然遵循这些规范并非强制要求,但这样做无疑符合每个人的切身利益。

我们无法承诺立即修复每一个 Bug。如果该缺陷显而易见、属于严重故障或影响了大量用户,通常会有核心开发者及时跟进。我们也可能会建议你升级到更新的维护版本,以验证该问题是否已在新版本中解决。有时我们可能会判断该缺陷在完成某些规划中的重大架构重构之前暂无法彻底解决;或者该问题极其棘手,当前开发日程中有更优先的事项需要处理。如果你需要即时的高级别技术保障,建议考虑购买商业技术支持服务。

5.1. 识别 Bug #

在提交 Bug 报告之前,请务必仔细通读官方文档,确认你所尝试的操作确实属于系统支持的功能范畴。如果文档对于某项操作是否被支持表述不清,也欢迎对此进行反馈,这同样属于文档缺陷。如果程序的实际运行行为与文档描述不符,即可明确判定为 Bug。常见的情形包括:

  • 程序因致命信号(fatal signal)或操作系统底层错误提示异常终止,表明程序内部发生了故障(反例是“磁盘空间已满”等系统提示,此类情况属于系统运维层面的资源问题,需自行解决)。

  • 对于任何给定的有效输入,程序产生了错误的输出结果。

  • 程序拒绝接收符合文档规范的合法输入。

  • 程序在面对非法输入时未抛出任何告警或错误提示直接接受。但请注意,你认为的非法输入可能正是社区为了向后兼容或功能扩展所支持的设计。

  • 在官方支持的软硬件平台上,完全按照官方文档指引却无法正常编译、构建或安装 PostgreSQL。

此处的“程序”是指系统的任何可执行组件,不仅限于后台服务进程。

运行缓慢或资源占用过高本身并不一定属于 Bug。请先查阅文档或在官方邮件列表中寻求关于应用架构与配置调优的建议。未能完全兼容 SQL 标准的所有细节也不必然属于 Bug,除非官方针对该特定特性明确声明了对标准的兼容性支持。

在提交报告前,请先查阅官方 TODO 列表与 FAQ,确认该问题是否已被官方记录。如果你无法完全理解 TODO 列表中的技术细节,请直接提交报告,这至少能帮助我们把开发待办说明写得更通俗易懂。

5.2. 应报告哪些内容 #

撰写 Bug 报告时最核心的原则是:完整客观地陈述所有已知事实,且只陈述事实。不要主观推测你认为出了什么错、系统“看起来像是做了什么”、或者怀疑哪个代码模块存在问题。如果你不熟悉底层实现细节,推测很可能会出现偏差,对排查无益;即使你很熟悉代码,合理的分析也是事实的补充,绝不能替代事实本身。要修复缺陷,开发者必须首先能在自己的环境中复现现象。客观陈述事实通常非常简单(直接从终端屏幕复制粘贴即可),但关键细节常常因为报告者主观认为“无关紧要”或“对方肯定能懂”而被遗漏。

一份合格的 Bug 报告应当包含以下要素:

  • 能够复现该问题的完整确切操作序列,必须从程序启动开始算起。该步骤必须具备自闭环性(self-contained):如果输出结果依赖于数据表中的数据,那么仅发送一个孤立的 SELECT 语句是完全不够的,必须附带前置的 CREATE TABLE 与 INSERT 初始化语句。开发团队没有时间去逆向猜测你的数据库 Schema 设计,如果让我们自行捏造测试数据,很可能无法触发真正的缺陷。

    针对 SQL 相关问题,最高效的测试用例格式是提供一个可直接在 psql 命令行前端运行并重现故障的 SQL 脚本文件(请确保你的个人配置文件 ~/.psqlrc 中没有任何会干扰环境的自定义设置)。生成该脚本的简便方法是使用 pg_dump 导出构建复现环境所需的表结构与数据定义,随后在末尾附加引发异常的目标查询。鼓励将用例精简至最小可复现规模,但即便数据稍大也不必过于顾虑,只要故障具备确定复现性,我们就能定位问题根源。

    如果你的应用使用的是其他客户端开发接口(例如 PHP、Node.js、Python 等),请尽量在数据库层面分离出有问题的具体 SQL 语句。核心团队通常不会搭建整套 Web 服务器来复现你的应用层代码。无论如何,请务必提供确切的输入数据与环境参数,不要模糊猜测问题发生在“处理大文件”或“中等规模数据库”时,这类不明确的信息对定位问题毫无助益。

  • 你所得到的实际输出结果。请不要只用一句话概括为“系统报错了”或“程序崩溃了”。如果有错误信息,即使你无法理解其含义,也请完整贴出其原始提示。如果程序因操作系统级错误而终止,请指明具体的系统退出代码或信号。如果终端没有任何响应或静默退出,也请如实说明。即使在你的机器上测试用例必定导致崩溃,在开发者的硬件平台上可能表现完全不同。最可靠的方式是直接完整截取终端输出文本。

    Note

    在汇报错误信息时,请尽量获取最详尽的日志输出格式。在 psql 中,可在执行前运行 \set VERBOSITY verbose。如果是从数据库服务端日志中提取错误信息,请将运行时参数 log_error_verbosity 配置为 verbose,以记录完整技术细节。

    Note

    遇到致命严重错误时,客户端收到的单行报错可能并未包含全部上下文。请务必一并检查数据库服务端的后台运行日志。如果你尚未养成保留数据库服务器运行日志的习惯,现在正是开启该配置的最佳契机。

  • 明确说明你所期望的输出结果,这一点极为关键。如果你仅描述“运行此命令得到了这个输出”或“这不是我期望的结果”,开发者自行运行后很可能会认为输出符合逻辑、正是标准行为。我们不应耗费精力去猜测你每条命令背后的主观意图。尤其请避免简单宣称“SQL 标准不是这样规定的”或“Oracle 不是这样表现的”。从数千页的 SQL 标准中寻找某项边缘行为的权威依据是一项极其耗时的工作,开发团队也无法对市面上所有其他商业数据库的细微差异了如指掌(如果问题属于程序崩溃,此项可直接忽略)。

  • 所使用的任何命令行启动参数、环境变量配置,以及相对于默认配置发生过改动的配置文件内容。请务必提供精确的参数取值。如果你使用的是操作系统发行版预打包的服务,且该服务在系统开机时自动拉起,请说明系统服务具体的启动配置方式。

  • 你在安装、编译或初始化集群时,是否有任何与官方安装文档步骤不一致的操作。

  • 确切的 PostgreSQL 版本号。你可以通过连接数据库后运行 SELECT version(); 查询服务端的完整编译版本信息。绝大多数可执行文件也支持 --version 参数;至少 postgres --version 与 psql --version 应当能够正常输出版本号。如果对应命令不存在该选项,说明当前安装版本过于陈旧,应立刻进行大版本升级。如果你使用的是第三方打包版本(如官方 RPM 或 APT 仓库),请注明完整的软件包全名及子版本号。如果是从 Git 源码编译构建的开发分支,请提供具体的 Commit Hash。

    如果所运行的版本早于当前官方支持版本(如 18.6),核心团队通常会建议优先升级。每个新维护版本中都修复了大量历史缺陷,旧版本中遇到的 Bug 很可能在新版本中已被修正。社区对已结束生命周期(EOL)的陈旧版本仅能提供极其有限的排查支持;如需针对过往版本的长期维护,请考虑采购商业支持服务。

  • 操作系统与底层平台信息,包括操作系统内核名称与版本号、C 基础运行库版本、CPU 架构型号以及内存容量等。在绝大多数情况下,指明发行版名称与主次版本号即可,但不要默认所有人都熟悉特定发行版具体集成了哪些组件,也不要预设系统必定运行于 x86_64 架构。如果遇到了编译或构建层面的故障,请附带机器上的基础构建工具链信息(如 GCC/Clang 编译器版本、make 或 meson 版本等)。

即使写出来的 Bug 报告篇幅较长也不必顾虑,详尽的工程上下文至关重要。初次汇报就一次性提供完整信息,远好于后续反复来回追问细节。另一方面,如果你的复现输入文件极其庞大,可以在邮件中简要描述并先询问是否有人愿意接手排查。关于如何高效撰写缺陷报告,推荐阅读经典指导文章: 《如何有效地报告 Bug》。

不要将过多时间耗费在反复尝试“修改哪些输入能让问题绕过去”上,这通常无法帮助定位代码深层的根本原因。如果该 Bug 确实无法在短期内修复,后续仍有充裕时间去探索替代方案。同样,请勿在无把握的情况下耗费时间猜测代码为什么会写成这样,核心团队会很快在源码中定位症结所在。

在撰写技术报告时,请使用精准规范的术语。整个软件套件的正式名称为 “PostgreSQL”,有时简称为 “Postgres”。如果你特指的是某个后台处理进程,请明确指明,不要笼统宣称“PostgreSQL 崩溃了”。单个后台 Session 进程的异常终止与主守护进程 “postgres” 的崩溃具有完全不同的系统影响;当仅有一个连接中断时,请勿表述为“服务器崩了”,反之亦然。此外,如交互式命令行终端 “psql” 等客户端程序与后端服务器彼此高度解耦独立,请在报告中明确指出异常现象究竟发生在客户端还是服务端。

5.3. 向何处报告 Bug #

通常情况下,请将 Bug 报告直接发送至官方缺陷报告邮件列表: 。 邮件主题应具备明确描述性,推荐直接引用部分核心错误提示摘要。

另一种提交渠道是使用官方网站提供的缺陷汇报表单: 官方提交表单。 通过该网页表单提交的内容会自动格式化并投递至 邮件列表。

如果你的 Bug 报告涉及核心安全漏洞,且你不希望该信息立刻在公开归档中暴露,请切勿发送至公共的 pgsql-bugs 列表。请私下将漏洞细节直接反馈至官方安全团队邮箱: 。

请勿将 Bug 报告发送至普通用户讨论列表,例如 或 。这些列表面向日常使用答疑,订阅者通常不期望接收详细的系统缺陷排查,且他们通常也没有权限向代码库合入修复。

同样,请不要直接将初次汇报发往核心开发者讨论列表 。该列表用于深入探讨 PostgreSQL 下一代架构演进与内核开发,将缺陷汇报分流处理有利于提升社区协作效率。如果某项问题需要广泛的架构评审,开发者会在审核后视情况将其转入 pgsql-hackers 展开专题研讨。

如果你发现的是文档层面的描述错误或疏漏,最适宜的反馈渠道是官方文档邮件列表: 。在邮件中请指明具体对应的章节标题或在线页面链接。

如果你在非官方主力支持的边缘平台上遭遇了可移植性编译故障,可将信息发送至 ,以便社区与你协同推进对新平台的适配支持。

Note

为防范垃圾邮件泛滥,上述所有官方邮件列表均设置了审核机制(除非发件人已订阅该列表)。这意味着未订阅用户的邮件在投递并公开显示前会有轻微的人工审核延迟。如需订阅官方列表,请访问 https://lists.postgresql.org/ 查阅详细指引。