版本控制与兼容性¶
目标是在各版本之间保持 ABI 兼容性。 因此,做出了一些选择
大多数结构体不包含嵌入的字段或函数,而是使用自由函数,从而易于添加新函数。
枚举通过
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。