<code class="language-plaintext highlighter-rouge">ui</code> 扩展为您的本地 DuckDB 实例添加了用户界面。

该 UI 由 MotherDuck 构建和维护。您可以在 MotherDuck 文档中找到其功能的概述。

要求

• 一个带有浏览器的环境。
• 除 Wasm 外的任何 DuckDB 客户端，版本 1.2.1 或更高。

用法

从命令行启动 UI

duckdb -ui

从 SQL 启动 UI

CALL start_ui();

运行其中任何一个都将在您的默认浏览器中打开 UI。

UI 连接到启动它的 DuckDB 实例，因此您已加载的任何数据都将可用。由于此实例是一个本地进程（非 Wasm），它可以利用您本地环境的所有资源：所有核心、内存和文件。关闭此实例将导致 UI 停止工作。

UI 通过嵌入在 DuckDB 中的 HTTP 服务器提供服务。若要在不启动浏览器的情况下启动此服务器，请运行

CALL start_ui_server();

然后，您可以通过导航到 https://:4213 在浏览器中加载 UI。

要停止 HTTP 服务器，请运行

CALL stop_ui_server();

本地查询执行

默认情况下，DuckDB UI 完全在本地运行您的查询：您的查询和数据永远不会离开您的计算机。如果您想通过 UI 使用 MotherDuck，则必须明确选择并登录 MotherDuck。

配置

本地端口

HTTP 服务器的本地端口可以通过类似以下的 SQL 命令进行配置：

SET ui_local_port = 4213;

也可以使用环境变量 ui_local_port。

默认端口是 4213。（为什么？4 = D, 21 = U, 3 = C）

远程 URL

本地 HTTP 服务器从远程 HTTP 服务器获取 UI 文件，以便它们保持最新。

远程服务器的默认 URL 是 https://ui.duckdb.org。

可以通过类似以下的 SQL 命令配置备用远程 URL：

SET ui_remote_url = 'https://ui.duckdb.org';

也可以使用环境变量 ui_remote_port。

此设置主要用于测试目的。

请确保您信任配置的任何 URL，因为应用程序可以访问您加载到 DuckDB 中的数据。

由于此风险，仅当 allow_unsigned_extensions 启用时，此设置才会生效。

轮询间隔

UI 扩展在后台线程上轮询一些信息。它监视附加数据库列表的变化，并检测您何时连接到 MotherDuck。

这些检查完成所需时间很短，因此默认轮询间隔很短（284 毫秒）。您可以通过类似以下的 SQL 命令进行配置：

SET ui_polling_interval = 284;

也可以使用环境变量 ui_polling_interval。

将轮询间隔设置为 0 将完全禁用轮询。不建议这样做，因为 UI 中的数据库列表可能会过时，并且某些连接 MotherDuck 的方式将无法正常工作。

提示

使用 DuckDB UI 打开 CSV 文件

使用 DuckDB CLI 客户端，您可以使用 -cmd 参数启动 UI，并将 CSV 作为视图提供。

duckdb -cmd "CREATE VIEW view_name AS FROM 'filename.csv';" -ui

在只读模式下运行 UI

DuckDB UI 内部使用 DuckDB 表作为存储（例如，用于保存笔记本）。因此，不支持直接在只读数据库上运行 UI。

duckdb -ui -readonly read_only_test.db

在 UI 中，这将导致

Catalog Error: SET schema: No catalog + schema named "memory.main" found.

为解决此问题，请在另一个数据库文件上运行 UI

duckdb -ui ui_catalog.db

然后，打开一个笔记本并附加到该数据库

ATTACH 'test.db' (READ_ONLY) AS my_db;
USE my_db

限制

• UI 目前不支持基于 ARM 的 Windows 平台（windows_arm64 和 windows_arm64_mingw）。