跳转到主要内容
当服务器调用扩展中的函数时,它通过一组固定的 C 结构体传入参数并读回结果。自定义类型的工作方式相同:扩展在一个结构体中描述每个类型,服务器在你安装该扩展时以及每次服务器启动时读取该结构体。协议是这些结构体及其填写规则的一个带编号的版本。 每个新协议都会向这些结构体添加内容,但不会移动旧扩展所读取的字段,并且服务器会保留读取每个旧版稳定协议的代码。这就是服务器仍能加载为旧版协议构建的扩展的原因。 你不需要自己设置协议编号。构建扩展所用的 SDK 会设置它:每个 SDK 版本为一个稳定协议构建扩展,其开发版 ABI 头文件(-DVSQL_USE_DEV_ABI=ON)则为开发协议构建扩展。要将扩展迁移到更新的协议,请使用更新的 SDK 重新构建它。

服务器如何选择协议

当你安装扩展时,服务器提供其最新的协议,扩展则声明其构建时所针对的协议。然后服务器和扩展使用两个编号中较低的那个。例如,提供协议 4 的服务器会以协议 3 与为协议 3 构建的扩展通信,并且不会向该扩展提供协议 4 新增的任何功能。 要查看每个已安装扩展所用的协议,请查询 INFORMATION_SCHEMA.EXTENSION_REGISTRATION:
NEGOTIATED_PROTOCOL 列保存服务器和扩展商定的协议。

稳定协议和开发协议

奇数编号的协议是稳定协议。目前服务器接受每一个稳定协议,一直追溯到协议 1,因此你为稳定协议构建的扩展无需重新构建即可继续安装到更新的服务器上。 偶数编号的协议是开发版本。服务器只接受它自己的开发协议,并且该协议的结构体可能在两个服务器构建版本之间发生变化。使用开发版 ABI 头文件(-DVSQL_USE_DEV_ABI=ON)构建的扩展可能在你更新服务器后停止工作。如果发生这种情况,请针对新服务器重新构建它。 当某个版本将开发协议提升为下一个稳定编号时,服务器会停止接受旧的开发编号。此时 INSTALL EXTENSION 会失败,并报错 extension uses obsolete unstable protocol version,后面跟着旧编号和当前编号。服务器启动时也会执行同样的检查,因此在安装有此类扩展的情况下服务器不会启动。在升级服务器之前,请针对新版本重新构建每一个使用开发版 ABI 头文件构建的扩展。
0.0.8-dev 中的变更。 协议 4 成为稳定协议 5,由 SDK 0.0.8 构建。0.0.8 的开发版 ABI 头文件构建协议 6。服务器拒绝协议 4,协议 4 不再受支持。协议 1 和 3 被弃用:服务器仍然接受它们,但新扩展应使用协议 5。

协议 3

SDK 0.0.4 至 0.0.7 构建协议 3 扩展。
0.0.8-dev 中的变更。 你使用这些 SDK 之一构建的扩展在更新的服务器上继续工作,行为不变,你不需要重新构建它。如果你使用 0.0.8 SDK 重新构建它,它会迁移到协议 5,并可以使用以下功能:
  • .max_result_length(),用于设置 STRING 或 BINARY 函数结果列的大小,使物化结果不会被截断至参数宽度。
  • 加载和卸载钩子,即 .on_init() 和 .on_deinit()。
  • 可变长度自定义类型,即 .variable_length_type()。
  • 用于原始字节的 BINARY 参数和结果类型。
  • 自定义类型的二进制形式,即 .from_binary() 和 .to_binary(),可在 SQL 中以 TYPE::from_binary 和 TYPE::to_binary 调用。
  • 能看到常量参数值的 prerun。
  • 在解析时进行类型检查,即 .bind_and_check_types()。
  • out.set() 会完整返回大于缓冲区的 STRING 值,而协议 3 会截断该值。
  • 从函数中逃逸的异常会使语句失败并返回错误。
重新构建后有一处行为变化:协议 3 和协议 5 传递 STRING 参数的方式不同。协议 3 函数收到的是参数的原始字节,未经更改,使用参数自身的字符集。协议 5 函数收到的是 utf8mb4 文本形式的参数,由服务器从调用方的字符集转换而来。例如,latin1 字符串 _latin1 X'E9'(é)到达协议 3 函数时是单个字节 E9,到达协议 5 函数时是两个字节 C3 A9。如果参数是并非有效 utf8mb4 的二进制字符串,语句会失败:
在重新构建之前,请找出每一个从 STRING 参数读取原始字节的函数(例如哈希函数或加密函数),并将该参数声明为 BINARY。这同样适用于以协议 1 样式编写的扩展。

协议 1

协议 1 自 0.0.1 起一直保持稳定。服务器仍然接受它,但它很可能会在未来版本中被弃用。请使用 使用 C++ 创建扩展 和 C++ 开发 指南中的类型化 API 编写新扩展。本节是以协议 1 样式编写的现有扩展的参考。更新的 SDK 仍能编译这种样式,并为其自身的稳定协议构建该扩展。
0.0.8-dev 中的变更。 协议 1 被弃用。服务器仍然接受它,但新扩展应使用协议 5。

函数指针类型 API

协议 1 中的自定义类型使用显式函数指针进行注册,而不是使用 vsql::make_type<> 模板。函数签名与类型化的等效签名不同。它们接受原始指针和长度,而不接受 Arg 和 Result 对象。

函数签名

注册

这种形式需要 #include <villagesql/extension.h>(而不是 <villagesql/vsql.h>)以及 using namespace villagesql;。
vsql::make_type<kMyTypeName>()(带有编译时字符串 NTTP)是首选形式。make_type(MYTYPE)(没有模板参数)是协议 1 形式——它仍受支持,但很可能会在未来版本中被弃用。

原始 ABI 样式(函数)

协议 1 VDF 实现可以直接传递原始 C 结构体,而不是使用类型化包装器。这种样式仍受支持,但很可能会在未来版本中被弃用——对于所有新代码,请使用 类型化参数/结果 API。
这种逐参数传递的原始签名——void(vef_context_t*, vef_invalue_t* arg0, ..., vef_vdf_result_t*)——只有来自 <villagesql/extension.h> 的 make_func<>() 才能识别。来自 <villagesql/vsql.h> 的 make_func<>() 会在编译时拒绝任何原始的 vef_context_t*/vef_invalue_t*/vef_vdf_result_t* 签名。

结果常量

原始 ABI 通过在 result->type 上设置的 vef_return_value_type_t 来传达结果状态: 使用类型化 API 时,out.set()、out.set_null()、out.warning() 和 out.error() 会自动处理这一点。

协议 1 中的聚合注册

来自 <villagesql/extension.h> 的 make_func<>() 构建器没有 .clear<>() 或 .accumulate<>() 成员。这些方法只存在于来自 <villagesql/vsql.h> 的独立构建器 make_aggregate_func<State, &result_fn>() 上,该构建器使用基于 State& 的类型化签名,而不是原始的 vef_context_t*/vef_vdf_args_t* 指针。对于所有新代码,请使用 类型化聚合方法。VEF_PROTOCOL_3 或更高版本的原始注册也可以手动在 vef_func_desc_t 中设置 clear 和 accumulate 回调。