扩展版本控制

大多数软件都有某种版本号。版本号有几个重要的目的：

• 将二进制文件绑定到源代码的特定状态
• 允许确定预期的功能集
• 允许确定API的状态
• 允许高效处理错误报告（例如，错误 #1337 是在版本 v3.4.5 中引入的）
• 允许确定发布的时序顺序（例如，版本 v1.2.3 比 v1.2.4 旧）
• 给出预期的稳定性指示（例如，v0.0.1 可能不太稳定，而 v13.11.0 可能是稳定的）

就像DuckDB本身一样，DuckDB扩展也有自己的版本号。为了确保这些版本号在各种扩展中的语义一致性，DuckDB的核心扩展使用了一个版本控制方案，规定了扩展应该如何进行版本控制。核心扩展的版本控制方案由3个不同的稳定性级别组成：不稳定、预发布和稳定。让我们逐一介绍这3个级别并描述它们的格式：

不稳定的扩展

不稳定扩展是指那些无法（或不愿意）就其当前稳定性或成为稳定版本的目标提供任何保证的扩展。不稳定扩展会被标记上扩展的短git哈希值。

例如，在撰写本文时，vss 扩展的版本是 690bfc5 版本的不稳定扩展。

对于一个版本号采用不稳定格式的扩展，我们可以期待什么？

• 可以通过在扩展仓库中查找哈希值来找到扩展源代码的状态
• 功能可能会随着每个版本的发布而改变或完全移除
• 此扩展的API可能会随着每次发布而更改
• 此扩展可能不遵循结构化的发布周期，新的（破坏性的）版本可能随时推送

预发布扩展

预发布扩展是从不稳定扩展升级的下一步。它们使用SemVer格式的版本进行标记，更具体地说，是那些使用v0.y.z格式的版本。 在语义版本控制中，以v0开头的版本具有特殊含义：它们表示常规版本（>v1.0.0）的更严格语义尚未适用。这基本上意味着一个扩展正在努力成为一个稳定的扩展，但还没有完全达到目标。

例如，在撰写本文时，delta 扩展的版本是 v0.1.0 的预发布版本。

从具有预发布格式版本号的扩展中可以期待什么？

• 该扩展是从与标签对应的源代码编译的。
• 语义版本控制语义适用。详情请参阅语义版本控制规范。
• 该扩展遵循一个发布周期，其中新功能在夜间构建中进行测试，然后被分组到一个版本中并推送到core仓库。
• 应提供描述每个版本新增内容的发布说明，以便于理解版本之间的差异。

稳定扩展

稳定扩展是扩展稳定性的最后一步。这通过使用格式为vx.y.z的稳定SemVer来表示，其中x>0。

例如，在撰写本文时，parquet 扩展的版本是 v1.0.0 的稳定扩展。

从具有稳定格式版本号的扩展中可以期待什么？基本上与预发布扩展相同，但现在应用了更严格的SemVer语义：扩展的API现在应该是稳定的，并且只有在主版本号增加时才会以不兼容的方式更改。详情请参阅SemVer规范。

预发布和稳定核心扩展的发布周期

一般来说，扩展的发布周期取决于它们的稳定性级别。不稳定的扩展通常与DuckDB的发布周期同步，但也可能在DuckDB发布之间悄悄更新。预发布和稳定的扩展遵循它们自己的发布周期。这些可能与DuckDB的发布周期一致，也可能不一致。要了解特定扩展的发布周期，请参考相应扩展的文档或GitHub页面。通常，预发布和稳定的扩展会在GitHub上记录它们的发布，你可以在delta扩展中看到一个例子。

最后，有一个小例外：所有in-tree扩展只需遵循DuckDB的发布周期。

夜间构建

就像DuckDB本身一样，DuckDB的核心扩展也有夜间或开发版本，可以在它们正式发布之前尝试新功能。 当您的工作流程依赖于新功能时，或者当您需要确认您的堆栈与即将发布的版本兼容时，这可能非常有用。

由于目前DuckDB扩展二进制文件与单个DuckDB版本紧密绑定，因此扩展的夜间构建稍微复杂一些。由于这种紧密连接，存在组合爆炸的潜在风险。因此，并非所有夜间扩展构建和夜间DuckDB构建的组合都可用。

一般来说，有两种使用夜间构建的方式：使用DuckDB的夜间构建和使用DuckDB的稳定构建。让我们来看看两者之间的区别：

From Stable DuckDB

在大多数情况下，用户可能对特定扩展的夜间构建感兴趣，但不一定希望切换到使用DuckDB本身的夜间构建。这允许使用特定的前沿功能，同时限制对不稳定代码的暴露。

为了实现这一点，Core Extensions 倾向于定期将构建推送到 core_nightly 仓库。让我们看一个例子：

首先我们安装一个稳定的DuckDB构建。

然后我们可以像这样安装并加载一个夜间扩展：

INSTALL aws FROM core_nightly;
LOAD aws;

在这个例子中，我们使用了aws扩展的最新nightly版本与DuckDB的最新stable版本。

From Nightly DuckDB

当DuckDB CI生成DuckDB本身的夜间二进制文件时，这些二进制文件会附带一组固定版本的扩展。这些扩展版本将针对该特定版本的DuckDB进行测试，但可能不是最新的开发版本。让我们看一个例子：

首先，我们安装一个nightly DuckDB 构建。然后，我们可以按照预期安装并加载aws扩展：

INSTALL aws;
LOAD aws;

更新扩展

DuckDB 有一个专门的语句，可以自动将所有扩展更新到最新版本。输出将向用户提供有关哪些扩展更新到/从哪个版本的信息。例如：

UPDATE EXTENSIONS;

请注意，DuckDB 会在源仓库中查找每个扩展的更新。因此，如果扩展是从 core_nightly 安装的，它将会更新为最新的 nightly 版本。

更新语句也可以提供要更新的特定扩展列表：

UPDATE EXTENSIONS (httpfs, azure);

目标 DuckDB 版本

目前，当扩展被编译时，它们会绑定到特定版本的DuckDB。这意味着，例如，为v0.10.3编译的扩展二进制文件不适用于v1.0.0。在大多数情况下，这不会引起任何问题，并且是完全透明的；DuckDB会自动确保为其版本安装正确的二进制文件。对于扩展开发者来说，这意味着每当DuckDB发布新版本时，他们必须确保创建新的二进制文件。然而，请注意，DuckDB提供了一个扩展模板，这使得这一过程相当简单。