DolphinDB 版本兼容性标准

1. 背景

为了便于用户了解 DolphinDB 版本升级的兼容性情况，降低版本升级可能带来的业务中断、数据丢失等风险，DolphinDB 针对服务器、SDK 和插件等制定了版本兼容性等级标准。1.30.17 和 2.00.5 版本以后，DolphinDB 将在 release notes 中注明新发布版本的兼容性等级。如有不兼容之处，将在 release notes 中详细写明并提供相应的解决方案。

本文主要对 DolphinDB 版本兼容性等级标准进行了定义和说明，用户可以参考各兼容性等级的要求，快速了解版本升级的潜在风险。为满足升级安全，DolphinDB 数据库服务器的最新版和稳定版升级至少满足向后兼容的要求。

2. 术语和定义

向后兼容（Backward Compatibility）：指新版本的软件可以兼容旧版本的软件，包括配置、数据和程序行为，即向过去兼容。

向前兼容（Forward Compatibility）：指旧版本的软件可以兼容新版本的软件，包括配置、数据和程序行为，即向未来兼容。

版本回退：指软件升级到新版本后，发现新版本运行有风险，又回退到升级前的版本。根据升级后数据库文件是否更新，又可以细分为三种情况：

（1）无条件回退。新版本没有更新数据库文件、日志文件和元数据的格式，无论升级后是否已经写入了数据，总是可以回退到旧版本。

（2）备份元数据后的回退。数据库文件格式没有发生变化，但元数据文件格式发生了变化。升级后重启的过程中，系统会对 edit log 做一次 checkpoint，生成新的元数据。那么回退到后，旧版本无法读取新格式的元数据文件。我们可以通过备份元数据来解决回退的问题。

（3）安全关机后的回退。数据库文件格式发生了变化。即使重启后用户没有主动写入数据，也有可能因为重放日志导致被动写入数据到数据库文件。这样回退到旧版本后无法读取数据。为解决这个问题，DolphinDB 从 1.30.17 和 2.00.5 版本开始支持安全关机，来确保关闭节点前 redo log 中数据全部写入数据库文件。

滚动升级：传统方式升级集群版本，通常先把全部节点关闭，然后一次性把整个集群全部节点的版本升级为新版本。按照该方式升级时，业务会被中断。滚动升级是指可以逐一按节点进行版本升级，在单个节点升级为新版本，并确保其稳定运行后，再升级集群内的另一个节点，以此类推，直至整个集群内的所有节点完成升级。

支持滚动升级，意味着内存中的数据格式，包括传输协议，序列化协议等需要完全兼容。

滚动升级过程中，系统一直保持在线，除了新的版本要符合很高的兼容性标准外，集群部署方式必须是高可用的，即控制节点采用高可用部署，数据节点的副本数为2个以上，客户端采用高可用写入。

插件和 SDK 的兼容性：兼容性包括二进制兼容和代码的兼容。对于插件而言，二进制兼容指的是旧版的插件（动态库）可以在新版的数据库服务器上加载并运行。代码兼容性指原有的脚本可以不做任何修改在新版本的插件上运行。一个插件如果满足二进制兼容性，就可以在升级数据库服务器时选择不升级插件。

对于 SDK（Python，C++，Java，C# 等）而言，二进制兼容性指旧版本的 SDK（通常为动态库的形式）兼容新版本的服务器。代码兼容性指 SDK 的接口兼容已有的客户端代码，无需修改客户端代码即可与新的 SDK 一起编译和链接。

3. 兼容性等级定义

为了用户直观了解各版本所满足的兼容性标准，DolphinDB 将兼容性需求划分为了五个等级。每一等级的标准均向下兼容较低等级的标准。等级越高，兼容性要求越严格。

3.1 一级兼容性标准

一级兼容性标准要求 DolphinDB Server 基本满足向后兼容的要求，以确保旧版本的数据和脚本能够在新版本环境下成功运行。但允许服务器删除部分声明 deprecation（即不建议继续使用）超过一年的内置函数。也允许插件代码不兼容，即用户必须升级插件的二进制库文件，修改调用插件函数的脚本。允许 SDK 二进制不兼容，即用户必须升级 SDK 的动态库，但能够保证代码兼容。

插件与 API 的兼容性等级要求不一样，是因为插件与 DolphinDB Server 在同一个进程中运行，插件的头文件往往随着 Server 的变化而变化，而 SDK 只需要与 Server 通信协议兼容即可。

• 具体要求包括：

1. 兼容旧版本的配置，即配置项的名称不能修改，默认值不能修改；
2. 兼容旧版本的函数和脚本，即函数名不能改，函数参数只能增加，并且新增参数需要有默认值，脚本的用法不能修改。但部分函数允许 deprecate 一年后不再支持；
3. 兼容旧版本的存储数据，包括分布式表数据，持久化的流表数据，定时任务，函数视图和用户权限数据等；
4. SDK 满足代码兼容性，即使用 SDK 写的客户端程序重新编译链接后可以继续运行。

• 升级指南：

1. 一级标准不支持插件代码兼容和 API 的二进制兼容。升级 Server 时，插件和 API 的二进制库文件必须升级，API 客户端需要重编，插件脚本可能需要修改；
2. 数据库文件格式可能有变，如要确保能回退，升级前必须安全关机以保证所有的 redo log 都已经回收 。

3.2 二级兼容性标准

二级兼容性标准实现全面向后兼容。要求 DolphinDB Server 满足一级兼容性标准，且在此基础上，兼容旧版本的全部函数和脚本；实现插件和 SDK 的代码兼容，插件在升级二进制文件后，用插件写的脚本能继续运行。

• 具体要求包括：

1. 兼容旧版本的配置；
2. 兼容旧版本的函数和脚本；
3. 兼容旧版本的存储数据，包括分布式表数据，持久化的流表数据，定时任务，函数视图和用户权限数据等；
4. 插件满足代码兼容性，即插件的二进制文件需要升级，但调用插件的脚本不需要修改；
5. SDK 满足代码兼容性，客户端代码只要用新的 SDK 进行编译和链接，就可以连接新版本的服务器。

• 升级指南：

1. 升级时，插件的二进制库文件可能需要升级；
2. 数据库文件格式可能有变，如要确保能回退，升级前必须安全关机以保证所有的 redo log 都已经回收 。

3.3 三级兼容性标准

三级兼容性标准在二级兼容性标准的基础上，实现插件和 SDK 的二进制兼容。

具体要求包括：

1. 兼容旧版本的配置；
2. 兼容旧版本的函数和脚本；
3. 兼容旧版本的存储数据，包括分布式表数据，持久化的流表数据，定时任务，函数视图和用户权限数据等；
4. 插件和 SDK 满足二进制兼容性，即插件和 SDK 不需要升级也能继续运行。

升级指南：

升级前必须做好控制节点和数据节点的元数据备份。回退时需要先恢复备份的旧版本的元数据。

3.4 四级兼容性标准

四级兼容性标准在三级兼容性标准的基础上，要求新版本能够有条件回退到旧版本，并支持滚动升级，即 DolphinDB 集群可以逐一按节点进行升级，一个节点更新版本并稳定运行后，再升级集群内另一个节点。在升级过程中，如果出现异常，也可快速回退到旧版本，大幅降低升级风险。

支持滚动升级，内存中的数据格式、传输协议等需要完全兼容。

具体要求包括：

1. 兼容旧版本的配置；
2. 兼容旧版本的函数和脚本；
3. 兼容旧版本的存储数据，包括分布式表数据，持久化的流表数据，定时任务，函数视图和用户权限数据等；
4. 插件和 SDK 满足二进制兼容性，即插件和 SDK 不需要升级也能继续运行；
5. 支持有条件回退。若新版本的存储数据未写入，版本能回退到旧版本继续运行。
6. 兼容旧版本的内存数据，包括内存表的数据，矩阵、向量等变量的数据，以及传输协议等，确保集群的各节点能滚动升级。

3.5 五级兼容性标准

五级兼容性标准是 DolphinDB 服务器的最高等级的兼容性标准，支持滚动升级，支持无条件回退到旧版本。

具体要求包括：

1. 兼容旧版本的配置；
2. 兼容旧版本的函数和脚本；
3. 兼容旧版本的存储数据，包括分布式表数据，持久化的流表数据，定时任务，函数视图和用户权限数据等；
4. 插件和 SDK 满足二进制兼容性，即插件和 SDK 不需要升级也能继续运行；
5. 兼容旧版本的内存数据，包括内存表的数据，矩阵、向量等变量的数据，以及传输协议等，确保集群的各节点能滚动升级；
6. 支持无条件回退到旧版本，即升级后，存储数据已写入新版本数据库，软件也能回退到旧版本继续运行，并为客户端正常提供服务。

3.6 兼容性标准汇总

各等级需要满足的兼容性要素如下表所示。

	配置	函数和脚本	存储数据	插件	SDK	滚动升级	版本回退
一级标准	兼容	可能删除声明 deprecation超过一年的内置函数	向后兼容	代码可能不兼容	代码兼容	可能不支持	安全关机后回退
二级标准	兼容	兼容	向后兼容	代码兼容	代码兼容	可能不支持	安全关机后回退
三级标准	兼容	兼容	向前兼容	无需更新	无需更新	可能不支持	备份元数据后回退
四级标准	兼容	兼容	向前兼容	无需更新	无需更新	支持	备份元数据后回退
五级标准	兼容	兼容	向前兼容	无需更新	无需更新	支持	无条件回退

4. DolphinDB版本兼容性等级的约定

DolphinDB 版本分稳定版、最新版和 Beta 版。通常经历 5-10 个小版本的迭代后，Beta 版升级成最新版，最新版升级成稳定版。

DolphinDB 服务器大版本间的升级，比如从 1.20 版本升级到 1.30 版本，1.30 版本升级到 2.00 版本，满足一级兼容性标准，个别情况满足二级兼容性标准。一级标准可能不支持插件的代码兼容和 SDK 的二进制兼容，升级时，插件和 SDK 的二进制库文件可能需要升级，API 客户端需要重编，调用插件函数的脚本需要更新，具体参考版本发布的 release notes。特别需要注意的是，一级和二级标准支持安全关机后的回退，升级前必须做好控制节点、数据节点的元数据的备份，且必须安全关机。

DolphinDB 服务器小版本或补丁（patch）间的升级，比如从 1.30.17 版本升级到 1.30.18 版本，一般满足四级和五级（最高级别）的兼容性标准，个别情况只满足三级标准。对 Beta 版小版本的升级，可能改动比较大，满足一级或二级兼容性标准。

跨版本升级的兼容性标准等级，取所有相邻两个版本的兼容性等级的最小值。譬如从 1.30.16 升级到 1.30.17 的兼容性等是四级，从1.30.17 升级到 1.30.18 的兼容性等是三级，那么从 1.30.16 升级到 1.30.18 的兼容性等级就是三级。对于版本跨度较大的升级，可联系 DolphinDB 的技术支持工程师，进行风险评估。