PAYATHON 2026

DuckDB CLI 如何记录 SQL 执行错误？

数据小陈

结论

DuckDB CLI 中，duckdb_logs 里的 QueryLog 记录能说明查询文本已被记录，但不能证明查询执行失败时 CLI 显示的错误正文也写入了日志。命令行流水线可以单独将 CLI 的标准错误重定向到文件，以保存实际显示的错误信息。如果还要查询 DuckDB 生成的日志，可以显式选择 memory 存储，再查询 duckdb_logs。

在流水线中收集 CLI 错误

在 macOS shell 中，可以这样运行 SQL 文件：

duckdb my.db < script.sql >run.stdout 2>run.stderr

run.stdout 保存标准输出，run.stderr 保存标准错误。示例中的 Binder Error 是 CLI 显示的语句执行错误。即使 duckdb_logs 中有对应的 QueryLog 查询文本，也不能据此断定错误正文写入了日志。

要合并两路输出，可以使用：

duckdb my.db < script.sql >run.log 2>&1

合并后，无法再仅凭文件区分标准输出和标准错误。DuckDB CLI 默认将查询结果输出到标准输出，shell 重定向可以分别保存两个输出流。DuckDB CLI 文档

查询 DuckDB 日志

如果要在同一次 CLI 会话中检查日志存储，可以在执行脚本前设置 memory 存储：

CALL enable_logging(storage = 'memory', level = 'INFO');

-- 在这里执行待检查的 SQL

SELECT timestamp, type, log_level, message
FROM duckdb_logs()
WHERE log_level IN ('ERROR', 'FATAL');

DuckDB 文档说明，CLI 默认使用的 shell_log_storage 会将日志打印到控制台，无法通过 duckdb_logs 查询。要查询日志，需要切换到 memory 等可查询的存储。文档还区分了日志级别和日志类型：设置日志级别或添加 QueryLog 类型，都不能保证所有 SQL 语句异常都会以错误日志的形式保存。DuckDB Logging 文档

切换到 memory 后，如果仍看不到某条语句的错误正文，仍可用 2>run.stderr 保存 CLI 报错。内存日志只在当前进程会话中可用，标准错误文件则由 shell 写入磁盘。

建议

如果流水线需要留存每次执行的错误，优先使用标准错误重定向，并按运行批次命名输出文件。duckdb_logs 可用于检查 DuckDB 记录的日志事件；仅凭 QueryLog 中有查询文本，不能认定日志也包含 CLI 输出的异常详情。

备注：内容仅供参考。