DuckDB：灵活扩展机制

Whoisbug

已于 2025-01-25 13:11:19 修改

阅读量1.1k

点赞数 12

分类专栏： SQL引擎文章标签： sql duckdb c++ cpp python 数据库 olap

于 2025-01-25 01:06:32 首次发布

本文链接：https://blog.youkuaiyun.com/Whoisbug/article/details/145348565

版权

SQL引擎专栏收录该内容

15 篇文章

订阅专栏

DuckDB 拥有一个灵活的扩展机制，允许动态加载扩展。这些扩展可以通过提供对额外文件格式的支持、引入新类型以及特定领域的功能来扩展 DuckDB 的功能，常用于异构数据源的无差别SQL查询与导入，十分便利。

🌈 扩展在DuckDB中的应用可参考：依赖管理在 DuckDB 扩展中的应用

注意

扩展可以在所有客户端（例如 Python 和 R）上加载。通过核心和社区仓库分发的扩展在 macOS、Windows 和 Linux 上构建和测试。所有操作系统均支持 AMD64 和 ARM64 架构。

列出扩展

要获取扩展列表，请使用 duckdb_extensions：

SELECT extension_name, installed, description
FROM duckdb_extensions();

extension_name	installed	description
arrow	false	在 DuckDB 和 Apache Arrow 之间提供零拷贝数据集成
autocomplete	false	在 shell 中添加自动补全支持
…	…	…

此列表将显示哪些扩展可用、哪些扩展已安装、版本号、安装位置等信息。列表中包含大多数（但不是全部）核心扩展。完整的扩展列表可以在 DuckDB 核心扩展列表中找到。

内置扩展

DuckDB 的二进制发行版默认包含一些内置扩展。这些扩展静态链接到二进制文件中，可以直接使用。例如，使用内置的 json 扩展读取 JSON 文件：

SELECT *
FROM 'test.json';

为了使 DuckDB 发行版保持轻量级，只有少数基本扩展是内置的，具体因发行版而异。哪些扩展在哪个平台上是内置的，可以在 DuckDB 核心扩展列表中找到。

安装更多扩展

要将非内置扩展在 DuckDB 中使用，需要执行两个步骤：

扩展安装 是下载扩展二进制文件并验证其元数据的过程。在安装过程中，DuckDB 会将下载的扩展及其一些元数据存储在本地目录中。从这个目录中，DuckDB 可以在需要时加载扩展。这意味着安装只需要执行一次。
扩展加载 是将二进制文件动态加载到 DuckDB 实例中的过程。DuckDB 会在本地扩展目录中搜索已安装的扩展，然后加载它以使其功能可用。这意味着每次重启 DuckDB 时，所有使用的扩展都需要重新加载。

注意

扩展的安装和加载受到一些限制。

扩展的安装和加载可以通过两种主要方式完成：显式和 自动加载。

显式 `INSTALL` 和 `LOAD`

在 DuckDB 中，扩展也可以显式安装和加载。非自动加载扩展和自动加载扩展都可以通过这种方式安装。要显式安装和加载扩展，DuckDB 提供了专用的 SQL 语句 LOAD 和 INSTALL。例如，要安装和加载 spatial 扩展，请运行：

INSTALL spatial;
LOAD spatial;

通过这些语句，DuckDB 将确保 spatial 扩展已安装（如果已安装则忽略 INSTALL 语句），然后继续加载 spatial 扩展（如果已加载则忽略该语句）。

扩展仓库

可以通过在 INSTALL / FORCE INSTALL 命令后附加 FROM <repository> 来指定扩展的安装来源。此仓库可以是别名（如 community），也可以是直接提供的 URL（作为单引号字符串）。

安装/加载扩展后，可以使用 duckdb_extensions 函数获取更多信息。

自动加载扩展

对于 DuckDB 的许多核心扩展，显式加载和安装扩展是不必要的。DuckDB 包含一个自动加载机制，可以在扩展在查询中使用时自动安装和加载核心扩展。例如，运行以下语句时：

SELECT *
FROM 'https://raw.githubusercontent.com/duckdb/duckdb-web/main/data/weather.csv';

DuckDB 将自动安装和加载 httpfs 扩展。无需显式执行 INSTALL 或 LOAD 语句。

并非所有扩展都可以自动加载。原因可能多种多样：一些扩展会对正在运行的 DuckDB 实例进行多项更改，使得自动加载在技术上（暂时）不可行。对于其他扩展，由于它们修改了 DuckDB 中的行为方式，更倾向于让用户在使用前明确选择扩展。

要查看哪些扩展可以自动加载，请查看 DuckDB 核心扩展列表。

DuckDB 支持安装第三方社区扩展。这些扩展由社区成员贡献，但在集中仓库中构建、签名和分发。

通过客户端 API 安装扩展

对于许多客户端，使用 SQL 加载和安装扩展是首选方法。然而，一些客户端有专用的 API 来安装和加载扩展。例如 Python API 客户端，它有专用的 install_extension(name: str) 和 load_extension(name: str) 方法。有关特定客户端 API 的更多详细信息，请参阅客户端 API 文档。

更新扩展

虽然内置扩展由于其静态链接到 DuckDB 二进制文件的性质而与 DuckDB 发行版绑定，但可安装扩展可以并且会收到更新。要确保所有已安装的扩展都是最新版本，请调用：

CALL duckdb_update_extensions();

有关扩展版本的更多详细信息，请参阅扩展版本控制。

安装位置

默认情况下，扩展安装在用户的主目录下：

~/.duckdb/extensions/<duckdb_version>/<platform_name>/

对于稳定的 DuckDB 发行版，<duckdb_version> 将等于该发行版的版本标签。对于夜间构建的 DuckDB，它将等于构建的短 Git 哈希值。例如，DuckDB 版本 v0.10.3 在 macOS ARM64（Apple Silicon）上的扩展安装路径为 ~/.duckdb/extensions/v0.10.3/osx_arm64/。夜间构建的 DuckDB 的示例安装路径可能是 `~/.duckdb/extensions/fc2e4b26a6/linux_amd64_gcc4。

要更改 DuckDB 存储扩展的默认位置，请使用 extension_directory 配置选项：

SET extension_directory = '/path/to/your/extension/directory';

请注意，设置 home_directory 配置选项的值不会影响扩展的存储位置。

二进制兼容性

为了避免二进制兼容性问题，DuckDB 分发的二进制扩展与特定的 DuckDB 版本和平台绑定。这意味着 DuckDB 可以自动检测它与可加载扩展之间的二进制兼容性。尝试加载为不同版本或平台编译的扩展时，DuckDB 将抛出错误并拒绝加载该扩展。

有关可用平台的更多详细信息，请参阅使用扩展页面。

开发扩展

核心扩展所使用的 API 也可用于开发扩展。这允许用户扩展 DuckDB 的功能，使其最适合他们的领域。扩展开发的模板可在 extension-template 仓库中找到。该模板还包含一些关于如何开始构建自己的扩展的文档。

扩展签名

扩展使用加密密钥进行签名，这也简化了分发（这就是为什么它们通过 HTTP 而不是 HTTPS 提供的原因）。默认情况下，DuckDB 使用其内置的公钥在加载扩展之前验证扩展的完整性。DuckDB 核心团队提供的所有扩展都已签名。

未签名扩展

警告

只有从您信任的来源加载未签名扩展。此外，避免通过 HTTP 加载它们。

如果您希望加载自己的扩展或第三方扩展，您需要启用 allow_unsigned_extensions 标志。要使用 CLI 客户端加载未签名扩展，请在启动时向其传递 -unsigned 标志：

duckdb -unsigned

现在可以加载任何扩展，无论是已签名还是未签名：

LOAD './some/local/ext.duckdb_extension';

对于客户端 API，需要设置 allow_unsigned_extensions 数据库配置选项，具体请参阅相应的客户端 API 文档。例如，对于 Python 客户端，请参阅 Python API 文档中的加载和安装扩展部分。

使用扩展

有关高级安装说明和更多扩展详细信息，请参阅使用扩展页面。