CLI API

v1.1.3 19864453f7
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;

my_column
嘎嘎

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

编辑器功能

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

退出CLI

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

Dot Commands

除了SQL语法外，特殊的点命令也可以输入到CLI客户端中。要使用这些命令之一，请在行首输入一个句点（.），紧接着输入您希望执行的命令名称。命令的附加参数在命令后以空格分隔输入。如果参数必须包含空格，可以使用单引号或双引号包裹该参数。点命令必须在一行内输入，且句点前不能有空格。行末不需要分号。

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

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

打开数据库文件

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

.open

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

.open persistent.duckdb

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

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

.open --readonly preexisting.duckdb

输出格式

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

将结果写入文件

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

从文件中读取SQL

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

.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"

加载扩展

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

INSTALL fts;
LOAD fts;

详情请参阅扩展文档。

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

在Unix环境中，在多个命令之间传输数据可能非常有用。 DuckDB能够使用SQL命令中的stdin文件位置（/dev/stdin）和stdout文件位置（/dev/stdout）从stdin读取数据以及写入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')"

woot
42
43

要写回到标准输出，可以使用/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 函数可以读取环境变量。

Examples

要从HOME环境变量中获取主目录的路径，请使用：

SELECT getenv('HOME') AS home;

首页
/Users/用户名

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

SET default_null_order = getenv('DEFAULT_NULL_ORDER');

读取环境变量的限制

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

Prepared Statements

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

Installation

入门指南

Usage

Options

内存数据库 vs. 持久化数据库