DuckDB 通过广泛的测试套件进行了全面的测试。尽管如此，依然可能出现漏洞，且有时会导致崩溃。本页面包含有关如何排查 DuckDB 崩溃问题的实用信息。

崩溃类型

主要有以下几种类型的崩溃：

• 终止信号： 进程以 SIGSEGV（段错误）、SIGABRT 等信号停止：这种情况不应该发生。请提交问题报告。

• 内部错误： 操作可能会导致 Internal Error（内部错误），例如：

  INTERNAL Error:
  Attempted to access index 3 within vector of size 3
  

  遇到内部错误后，DuckDB 会进入受限模式，任何后续操作都将导致以下错误消息：

  FATAL Error:
  Failed: database has been invalidated because of a previous fatal error.
  The database must be restarted prior to being used again.
  

• 内存溢出错误： DuckDB 的崩溃也可能是操作系统终止进程的征兆。例如，许多 Linux 发行版运行 OOM（Out of Memory）清除程序或 OOM Killer 进程，它会终止进程以释放内存，从而防止操作系统内存耗尽。如果您的 DuckDB 会话被 OOM 清除程序终止，请参阅“OOM 错误”页面。

数据恢复

如果您的 DuckDB 会话在崩溃前正在写入持久化数据库文件，则数据库旁边可能存在一个名为 database_filename.wal 的 WAL（预写式日志）文件。要从 WAL 文件恢复数据，只需在持久化数据库上启动一个新的 DuckDB 会话。DuckDB 将重放预写式日志并执行检查点操作，将数据库恢复到崩溃前的状态。

排查崩溃问题

使用最新的稳定版和预览版构建

DuckDB 正在不断改进，因此您遇到的漏洞可能已经在代码库中得到修复。首先，尝试更新到最新的稳定版本。如果这不能解决问题，请尝试使用预览版本（也称为“每日构建版”）。

如果您希望在应用了开放拉取请求 (Pull Request) 的代码库上使用 DuckDB，您可以尝试从源代码进行构建。

搜索现有问题

很有可能其他人已经报告过导致崩溃的漏洞。请在 GitHub 问题追踪器 中搜索错误消息，查看是否有相关的问题。DuckDB 拥有庞大的社区，可能已经有人提供了解决方案或变通方法。

禁用查询优化器

有些崩溃是由 DuckDB 的查询优化器组件引起的。要确认是否是优化器导致了崩溃，请尝试将其关闭并重新运行查询：

PRAGMA disable_optimizer;

如果查询成功完成，则说明崩溃是由一个或多个优化规则引起的。为了精确定位导致崩溃的具体规则，您可以尝试选择性地禁用优化器规则。这样，您的查询仍然可以受益于其余的优化规则。

尝试隔离问题

有些问题是由不同组件和扩展之间的相互作用引起的，或者特定于某些平台或客户端语言。您通常可以将问题缩小到更小的范围内进行排查。

在纯 SQL 中重现

问题也可能由于客户端库的差异而产生。要了解是否属于这种情况，请尝试使用 DuckDB CLI 客户端通过纯 SQL 查询重现该问题。如果您无法在命令行客户端中重现该问题，则它很可能与客户端库有关。

不同的硬件设置

根据我们的经验，一些崩溃是由于硬件故障引起的（硬盘过热、CPU 超频等）。因此，尝试在另一台计算机上运行相同的负载是值得的。

分解查询

尝试将查询分解为多个较小的查询是个好主意，每个查询使用单独的 DuckDB 扩展和 SQL 功能。

例如，如果您的查询针对 AWS S3 存储桶中的数据集并对其执行了两次连接 (join)，请尝试将其重写为一系列较小的步骤，如下所示：手动下载数据集文件并将其加载到 DuckDB 中。然后分别执行第一次连接和第二次连接。如果多步方法在某一步仍然表现出崩溃，那么触发崩溃的查询就是构建最小可重现示例的良好基础。如果多步方法有效且不再崩溃，请尝试重构原始查询，观察是哪一步重新引入了错误。在这两种情况下，您都会更好地了解导致问题的原因，并可能找到可以立即使用的变通方法。无论如何，请考虑提交包含您的发现的问题报告。

提交问题报告

如果您发现了 DuckDB 的崩溃问题，请考虑在我们的 GitHub 问题追踪器 中提交一个包含最小可重现示例的问题。