DuckDB 命令行客户端的最新稳定版本是 1.5.0。

安装

DuckDB CLI（命令行界面）是一个单一的、无依赖的可执行文件。它为 Windows、Mac 和 Linux 预编译了稳定版本以及通过 GitHub Actions 生成的夜间构建版本。请参阅安装页面的 CLI 选项卡以获取下载链接。

DuckDB CLI 基于 SQLite 命令行 shell，因此 CLI 客户端特定的功能与 SQLite 文档中描述的内容类似（尽管 DuckDB 的 SQL 语法遵循 PostgreSQL 约定，且有少量例外）。

DuckDB 有一个 tldr 页面，其中总结了 CLI 客户端最常见的用法。如果你安装了 tldr，可以通过运行 tldr duckdb 来显示它。

入门

下载 CLI 可执行文件后，将其解压并保存到任意目录。在终端中导航到该目录，然后输入命令 duckdb 即可运行该程序。如果在 PowerShell 或 POSIX shell 环境中，请改用命令 ./duckdb。

用法

duckdb 命令的典型用法如下

duckdb ⟨OPTIONS⟩ ⟨FILENAME⟩

选项

OPTIONS（选项）部分用于配置 CLI 客户端的参数。常见选项包括

• -csv：将输出模式设置为 CSV
• -json：将输出模式设置为 JSON
• -readonly：以只读模式打开数据库（请参阅 DuckDB 中的并发处理）

有关选项的完整列表，请参阅命令行参数页面。

内存数据库与持久化数据库

当未提供 FILENAME 参数时，DuckDB CLI 将打开一个临时的内存数据库。你将看到 DuckDB 的版本号、连接信息以及以 D 开头的提示符。

duckdb

DuckDB v1.5.0 (Andium) 3a3967aa81
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
D

要打开或创建一个持久化数据库，只需将路径作为命令行参数包含进去即可

duckdb my_database.duckdb

在 CLI 中运行 SQL 语句

打开 CLI 后，输入以分号结尾的 SQL 语句，然后按回车键即可执行。结果将显示在终端的表格中。如果省略分号，按回车键将允许输入多行 SQL 语句。

SELECT 'quack' AS my_column;

CLI 支持 DuckDB 所有丰富的 SQL 语法，包括 SELECT、CREATE 和 ALTER 语句。

编辑器功能

CLI 支持自动补全，并且在某些平台上具有高级的编辑器功能和语法高亮功能。

退出 CLI

要退出 CLI，如果你的平台支持，请按 Ctrl+D。否则，请按 Ctrl+C 或使用 .exit 命令。如果你使用了持久化数据库，DuckDB 将自动执行检查点操作（将最新更改保存到磁盘）并关闭。这将删除 .wal 文件（预写式日志）并将所有数据合并到单一数据库文件中。

点命令

除了 SQL 语法外，还可以在 CLI 客户端中输入特殊的点命令。要使用这些命令之一，请以句点（.）开头，紧接着输入你想执行的命令名称。命令的其他参数以空格分隔，放置在命令之后。如果参数必须包含空格，可以使用单引号或双引号将该参数括起来。点命令必须在单行内输入，句点前不得有空格。行末不需要分号。

常用的配置可以存储在 ~/.duckdbrc 文件中，该文件将在启动 CLI 客户端时加载。有关这些选项的更多信息，请参阅下方的“配置 CLI”部分。

提示：若要防止 DuckDB CLI 客户端读取 ~/.duckdbrc 文件，请按如下方式启动

duckdb -init /dev/null

下面我们总结了一些重要的点命令。要查看所有可用命令，请参阅点命令页面或使用 .help 命令。

打开数据库文件

除了在打开 CLI 时连接到数据库外，还可以使用 .open 命令创建新的数据库连接。如果不提供额外参数，将创建一个新的内存数据库连接。当 CLI 连接关闭时，该数据库不会被持久化。

.open

.open 命令可选择性接受多个选项，但最后一个参数可用于指定持久化数据库的路径（或应创建该路径的位置）。特殊字符串 :memory: 也可用于打开临时内存数据库。

.open persistent.duckdb

警告：.open 会关闭当前数据库。若要在保留当前数据库的同时添加新数据库，请使用 ATTACH 语句。

.open 接受的一个重要选项是 --readonly 标志。这禁止对数据库进行任何编辑。要以只读模式打开，数据库必须已经存在。这也意味着无法以只读模式打开新的内存数据库，因为内存数据库是在连接时创建的。

.open --readonly preexisting.duckdb

输出格式

.mode 点命令可用于更改终端输出中表格的外观。其中包括默认的 duckbox 模式、用于被其他工具摄取的 csv 和 json 模式、用于文档的 markdown 和 latex 模式，以及用于生成 SQL 语句的 insert 模式。

将结果写入文件

默认情况下，DuckDB CLI 将结果发送到终端的标准输出。但是，这可以使用 .output 或 .once 命令进行修改。有关详细信息，请参阅输出点命令的文档。

从文件读取 SQL

DuckDB CLI 可以使用 .read 命令从外部文件读取 SQL 命令和点命令，而不是从终端读取。这允许按顺序运行多个命令，并可以将命令序列保存并重复使用。

.read 命令只需要一个参数：包含要执行的 SQL 和/或命令的文件路径。运行文件中的命令后，控制权将返回到终端。该文件的执行输出受上述 .output 和 .once 命令的控制。这允许输出显示回终端（如下面的第一个示例）或输出到另一个文件（如下面的第二个示例）。

在这个例子中，文件 select_example.sql 位于与 duckdb.exe 相同的目录中，并包含以下 SQL 语句

SELECT *
FROM generate_series(5);

要从 CLI 执行它，请使用 .read 命令。

.read select_example.sql

下方的输出默认返回到终端。表格的格式可以使用 .output 或 .once 命令进行调整。

| generate_series |
|----------------:|
| 0               |
| 1               |
| 2               |
| 3               |
| 4               |
| 5               |

多个命令（包括 SQL 和点命令）也可以在单个 .read 命令中运行。在这个例子中，文件 write_markdown_to_file.sql 位于与 duckdb.exe 相同的目录中，并包含以下命令

.mode markdown
.output series.md
SELECT *
FROM generate_series(5);

要从 CLI 执行它，请像之前一样使用 .read 命令。

.read write_markdown_to_file.sql

在这种情况下，没有输出返回到终端。相反，文件 series.md 被创建（如果已存在则被替换），并包含此处所示的 markdown 格式结果

| generate_series |
|----------------:|
| 0               |
| 1               |
| 2               |
| 3               |
| 4               |
| 5               |

配置 CLI

可以使用几个点命令来配置 CLI。启动时，CLI 会读取并执行文件 ~/.duckdbrc 中的所有命令，包括点命令和 SQL 语句。这允许你存储 CLI 的配置状态。你也可以使用 -init 指向不同的初始化文件。

设置自定义提示符

作为一个例子，在与 DuckDB CLI 相同的目录中创建一个名为 prompt.sql 的文件，将 DuckDB 提示符更改为鸭子头形状并运行一条 SQL 语句。请注意，鸭子头是使用 Unicode 字符构建的，并非在所有终端环境中都有效（例如在 Windows 上，除非使用 WSL 并使用 Windows Terminal）。

.prompt '⚫◗ '

要在初始化时调用该文件，请使用此命令

duckdb -init prompt.sql

这将输出

-- Loading resources from prompt.sql
v⟨version⟩ ⟨git_hash⟩
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
⚫◗

非交互式使用

要读取/处理文件并立即退出，请将文件内容重定向到 duckdb

duckdb < select_example.sql

要执行直接从命令行传递 SQL 文本的命令，请使用两个参数调用 duckdb：数据库位置（或 :memory:），以及包含要执行的 SQL 语句的字符串。

duckdb :memory: "SELECT 42 AS the_answer"

加载扩展

要加载扩展，请像使用其他 SQL 语句一样使用 DuckDB 的 SQL INSTALL 和 LOAD 命令。

INSTALL fts;
LOAD fts;

有关详细信息，请参阅扩展文档。

从 stdin 读取并写入 stdout

在 Unix 环境中，在多个命令之间通过管道传递数据非常有用。DuckDB 能够读取 stdin 的数据，并使用 SQL 命令中的 stdin 文件位置 (/dev/stdin) 和 stdout 文件位置 (/dev/stdout) 写入 stdout，因为管道的行为与文件句柄非常相似。

此命令将创建一个示例 CSV

COPY (SELECT 42 AS woot UNION ALL SELECT 43 AS woot) TO 'test.csv' (HEADER);

首先，读取一个文件并将其通过管道传给 duckdb CLI 可执行文件。作为 DuckDB CLI 的参数，传入要打开的数据库位置（在本例中为内存数据库），以及一个利用 /dev/stdin 作为文件位置的 SQL 命令。

cat test.csv | duckdb -c "SELECT * FROM read_csv('/dev/stdin')"

要写回 stdout，可以将 copy 命令与 /dev/stdout 文件位置一起使用。

cat test.csv | \
    duckdb -c "COPY (SELECT * FROM read_csv('/dev/stdin')) TO '/dev/stdout' WITH (FORMAT csv, HEADER)"

woot
42
43

读取环境变量

getenv 函数可以读取环境变量。

示例

要从 HOME 环境变量中检索主目录路径，请使用

SELECT getenv('HOME') AS home;

getenv 函数的输出可用于设置配置选项。例如，要基于环境变量 DEFAULT_NULL_ORDER 设置 NULL 的顺序，请使用

SET default_null_order = getenv('DEFAULT_NULL_ORDER');

读取环境变量的限制

getenv 函数仅在 enable_external_access 选项设置为 true（默认设置）时才能运行。它仅在 CLI 客户端中可用，在其他 DuckDB 客户端中不受支持。

预处理语句

DuckDB CLI 除了支持常规 SELECT 语句外，还支持执行预处理语句。要在 CLI 客户端中创建并执行预处理语句，请使用 PREPARE 子句和 EXECUTE 语句。

查询完成 ETA（预计完成时间）

DuckDB 的 CLI 现在为正在运行的查询提供智能的预计完成时间，并在完成后显示总执行时间。

在 DuckDB CLI 中执行查询时，进度条会显示距离完成的预计剩余时间。此功能采用高级统计建模（卡尔曼滤波）来提供比简单线性外推更准确的预测。

工作原理

DuckDB 通过以下过程计算预计完成时间

1. 进度监控：DuckDB 的内部进度 API 报告正在运行的查询的预计完成百分比
2. 统计过滤：卡尔曼滤波器平滑噪声进度测量并解释执行的变异性
3. 持续细化：系统随着新进度数据的可用，不断更新预计完成时间，从而在整个执行过程中提高准确性

卡尔曼滤波器能够适应不断变化的执行条件，例如内存压力、I/O 瓶颈或网络延迟。这种自适应方法意味着预计完成时间并不总是线性递减——当查询执行变得不可预测时，估计值可能会增加。

影响查询完成 ETA 准确性的因素

在以下条件下，完成时间估计可能不太可靠

系统资源限制

• 导致磁盘交换的内存压力
• 来自竞争进程的高 CPU 负载
• 磁盘 I/O 瓶颈

查询执行特征

• 可变的执行阶段（初始设置与主要处理）
• 具有不一致延迟的网络相关操作
• 具有不可预测分支逻辑的查询
• 对远程数据源的操作
• 外部函数调用
• 高度倾斜的数据分布