UI 扩展 – DuckDB - DuckDB 数据库

搜索快捷键 cmd + k | ctrl + k

文档 / 核心扩展

UI 扩展

ui 扩展为您的本地 DuckDB 实例添加了用户界面。

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

用法

通过命令行启动 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）

本地 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 CLI 客户端，您可以使用 -cmd 参数启动 UI，并将 CSV 作为视图加载

duckdb -cmd "CREATE VIEW view_name AS FROM 'filename.csv';" -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;