版本控制与兼容性¶

我们的目标是实现跨版本间的 ABI 兼容。因此，我们做出了一些选择：

大多数结构体不包含内嵌字段或函数，而是使用自由函数（free functions），这使得添加新函数变得简单。
枚举通过 typedef/#define 定义。

当然，我们永远不能添加/移除/修改结构体成员，也永远不能更改现有函数的签名。

在 ADBC 1.1.0 中，决定仅对“公共”API 执行此规则，而不适用于驱动程序内部 API（AdbcDriver）。该结构体在 1.1.0 版本中添加了新成员。兼容性处理方式如下：

驱动程序入口点 AdbcDriverInitFunc 会接收一个版本号以及一个指向待初始化函数指针表（AdbcDriver）的指针。表的大小取决于版本；当 ADBC 接受新版本时，可能会扩展新的函数指针表。对于每个版本，驱动程序都知道表的预期大小，并且不得读取/写入超出该大小的字段。如果/当我们添加新的 ADBC 版本时，会出现以下情况：

更新后的客户端应用程序使用旧的驱动程序库。客户端传递的 version 字段将大于驱动程序所识别的版本，因此驱动程序将返回 ADBC_STATUS_NOT_IMPLEMENTED，客户端可以决定是中止还是使用较旧的版本重试。
旧的客户端应用程序使用更新后的驱动程序库。客户端传递的 version 将小于驱动程序所识别的版本，因此驱动程序可以报错，或者如果它仍然能实现旧的 API 契约，则初始化对应于旧版本的表子集。

这种方法虽然不允许我们更改现有函数的签名，但我们可以添加新函数并移除现有函数。

版本控制¶

ADBC 的版本控制与核心 Arrow 项目是分开的。API 标准和组件（驱动管理器、驱动程序）也各自进行版本控制，但两者都遵循语义化版本控制。

例如：组件可能会发布向后兼容的版本，如 1.0.0、1.0.1、1.1.0、1.2.0 等。它们也可能发布向后不兼容的版本（如 2.0.0），但该版本仍然实现了 API 标准 1.0.0。

同样，本文档描述的是 ADBC API 标准 1.1.0 版本。如果/当做出兼容性修订（例如定义了新的标准选项或 API 函数）时，下一个版本将是 1.2.0。如果做出不兼容的更改（例如更改函数的签名或语义），下一个版本将是 2.0.0。

ADBC 驱动清单 TOML 格式的版本控制独立于 ADBC 标准和组件。其版本是一个整数，当前设为 1。该版本号可选择包含在清单中作为 manifest_version 键的值。如果存在，必须设为 1。如果不存在，则默认为 1。仅当驱动清单格式发生破坏性变更时，才必须递增清单版本号。在未来版本号高于 1 的清单中，manifest_version 键将成为必需项。当前的驱动管理器实现必须在读取版本号高于 1 的清单时报错。