DuckDB CLI 客户端的最新版本是 1.3.2。

安装

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.3.2 (Ossivalis) 0b83e5d2f6
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;

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

从标准输入读取并写入标准输出

在 Unix 环境中，在多个命令之间管道传输数据非常有用。DuckDB 能够使用 SQL 命令中的标准输入文件位置 (/dev/stdin) 和标准输出文件位置 (/dev/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')"

要写回标准输出，可以使用 /dev/stdout 文件位置的 copy 命令。

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 客户端不支持此功能。

预处理语句

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