搜索快捷键 cmd + k | ctrl + k
社区扩展开发

构建

DuckDB 提供一个基于 C++ 的扩展模板，该模板包含所有必需组件。该模板配置了包管理器vcpkg、一个基于 SQL 的测试框架以及一个基于 GitHub Actions 的 CI/CD 工具链。该 CI/CD 链将自动为所有支持的 DuckDB 平台（包括 Linux、MacOS、Windows 和 Wasm）构建您的扩展。

发布

要在 DuckDB 社区仓库中发布扩展，可以在社区仓库中打开一个拉取请求 (Pull Request)。在 PR 中，需要指定一个描述符文件，其中包含扩展的所有相关信息，例如其源仓库和版本。请查看现有社区扩展以获取示例。

社区仓库使用 DuckDB 的CI 工具链构建扩展，这意味着您的扩展需要能够使用此工具链进行构建。幸运的是，这与扩展模板使用的工具链完全相同，因此对于基于模板的扩展，这可以开箱即用。

开发者文档

鉴于 DuckDB 社区扩展是 DuckDB 生态系统的一个相对较新的补充，目前可用的开发者文档有限。信息可在以下位置找到：

然而，由于扩展模板的开箱即用特性以及大量的示例扩展，扩展开发应该相对简单。

如何通过 DuckDB 版本维护扩展

目前，社区扩展旨在仅为最新的稳定版 DuckDB 发布而构建和分发。这意味着使用非最新稳定版本的用户将看到社区扩展停滞不前，不再提供更新。

当下一个 DuckDB 版本临近时（请参阅发布日历），duckdb/community-extensions 仓库将切换为同时针对最新稳定版本和当前的main分支测试扩展。如果一个扩展同时兼容最新稳定版本和当前的main分支，那么该扩展不应受到新版本的影响。这通常是希望看到的情况。

如果一个扩展不同时兼容这两个分支，建议的更新路径如下：

  1. 拥有两个独立分支，一个针对最新稳定版，另一个针对main分支。
  2. 提供针对稳定版分支的最新提交哈希作为ref，以及针对 DuckDB 主分支的提交哈希作为ref_next。
  3. 这允许同时针对最新稳定版和当前的main分支测试扩展。
  4. 一旦设置了发布哈希，社区扩展将针对该 DuckDB 哈希进行构建，并且（如果存在）ref_next 将替换为ref。

例如，请参阅hannes/duckdb_avro的描述符，该描述符在 DuckDB v1.2.0 发布前几周发布。它在https://github.com/duckdb/community-extensions/pull/252/files中从

repo:
  github: hannes/duckdb_avro
  ref: e5ed59b6ccf915c65e17eb6286b9a64f3ab09f59

变为

repo:
  github: hannes/duckdb_avro
  ref: e5ed59b6ccf915c65e17eb6286b9a64f3ab09f59
  ref_next: c8941c92ec103f7825eb88207c04512f8a714b23

在这里，ref 的提交兼容 DuckDB v1.1.3 版本，而ref_next 兼容当前的 main 分支。

请注意，兼容当前 main 分支并不能保证与 v1.2.0 的兼容性，因为可能仍然会有影响扩展的更改，但这应该允许在新稳定版 DuckDB 发布之前尽早进行迭代。

获取帮助

对于与扩展开发相关的问题，在DuckDB Discord 服务器中有一个专用频道。Discord 服务器是获取其他扩展开发者和 DuckDB 核心团队帮助的好地方。如果您发现 DuckDB、扩展模板或 CI 工具链存在错误或其它类型的问题，请在相应的仓库中打开一个 issue 来描述您的问题。当然，如果您不确定，可以先在 Discord 频道中确认这是否是一个真正的问题，或者只是您使用不当。