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 兼容性标准汇总

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

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 的技术支持工程师，进行风险评估。