为了便于用户了解 DolphinDB 版本升级的兼容性情况，降低版本升级可能带来的业务中断、数据丢失等风险，DolphinDB 针对服务器、SDK 和插件等制定了版本兼容性等级标准。自1.30.17 和 2.00.5 版本起，DolphinDB 将在 release notes 中注明新发布版本的兼容性等级。如有不兼容之处，将在 release notes 中详细写明并提供相应的解决方案。
本文对 DolphinDB 版本兼容性等级标准进行了定义和说明，用户可以参考各兼容性等级的要求，快速了解版本升级的潜在风险。为满足升级安全，DolphinDB 数据库服务器的最新版和稳定版升级至少满足向后兼容的要求。
向后兼容（Backward Compatibility）：指新版本的软件可以兼容旧版本的软件，包括配置、数据和程序行为，即向过去兼容。
向前兼容（Forward Compatibility）：指旧版本的软件可以兼容新版本的软件，包括配置、数据和程序行为，即向未来兼容。
版本回退：指软件升级到新版本后，发现新版本运行有风险，又回退到升级前的版本。根据升级后数据库文件是否更新，又可以细分为三种情况：
（1）无条件回退。新版本没有更新数据文件、日志文件和元数据的格式，无论升级后是否已经写入了数据，总是可以回退到旧版本。
（2）备份元数据后的回退。数据文件格式没有发生变化，但元数据文件格式发生了变化。升级后重启的过程中，系统会对 edit log 做一次 checkpoint，生成新的元数据，但是回退到旧版本后，新格式的元数据文件将无法被读取。对此，我们可以通过在升级前备份元数据来解决这一问题。
（3）安全关机后的回退。数据文件格式发生了变化。即使重启后用户没有主动写入数据，也有可能因为重放日志导致被动写入数据到数据库文件。这样回退到旧版本后无法读取数据。为解决这个问题，DolphinDB 从 1.30.17 和 2.00.5 版本开始支持安全关机，来确保关闭节点前 redo log 中的数据全部写入数据库文件。
滚动升级：以传统方式升级集群版本，通常先把全部节点关闭，然后一次性把整个集群全部节点的版本升级为新版本。但是按照该方式升级时，业务会被中断。滚动升级是指可以逐一按节点进行版本升级，在单个节点升级为新版本，并确保其稳定运行后，再升级集群内的另一个节点，以此类推，直至整个集群内的所有节点完成升级。
支持滚动升级，意味着内存中的数据格式，包括传输协议，序列化协议等需要完全兼容。
滚动升级过程中，系统一直保持在线，除了新的版本要符合很高的兼容性标准外，集群部署方式必须是高可用的，即控制节点采用高可用部署，数据副本数至少为2，客户端采用高可用写入。
插件和 SDK 的兼容性：插件和SDK的兼容性包括二进制兼容和代码的兼容。
对于插件而言，二进制兼容指的是旧版的插件（动态库）可以在新版的数据库服务器上加载并运行。代码兼容性指原有的脚本可以不做任何修改在新版本的插件上运行。一个插件如果满足二进制兼容性，就可以在升级数据库服务器时选择不升级插件。
对于 SDK（Python，C++，Java，C# 等）而言，二进制兼容性指旧版本的 SDK（通常为动态库的形式）兼容新版本的服务器。代码兼容性指 SDK 的接口兼容已有的客户端代码，客户端代码无需修改即可与新的 SDK 一起编译和链接。
为了用户直观了解各版本所满足的兼容性标准，DolphinDB 将兼容性需求划分为了五个等级。每一等级的标准均向下兼容较低等级的标准。等级越高，兼容性要求越严格。
一级兼容性标准要求 DolphinDB Server 基本满足向后兼容的要求，以确保旧版本的数据和脚本能够在新版本环境下成功运行。但允许服务器删除部分声明 deprecation（即不建议继续使用）超过一年的内置函数。也允许插件代码不兼容，即用户必须升级插件的二进制库文件，修改调用插件函数的脚本。允许 SDK 二进制不兼容，即用户必须升级 SDK 的动态库，但能够保证代码兼容。
插件与 API 的兼容性等级要求不一样，是因为插件与 DolphinDB Server 在同一个进程中运行，插件的头文件往往随着 Server 的变化而变化，而 SDK 只需要与 Server 通信协议兼容即可。
- 具体要求包括：
- 兼容旧版本的配置，即配置项的名称不能修改，默认值不能修改；
- 兼容旧版本的函数和脚本，即函数名不能修改，函数参数只能增加，并且新增参数需要有默认值，脚本的用法不能修改。但部分函数允许 deprecate 一年后不再支持；
- 兼容旧版本的存储数据，包括分布式表数据，持久化的流表数据，定时任务，函数视图和用户权限数据等；
- SDK 满足代码兼容性，即使用 SDK 写的客户端程序重新编译链接后可以继续运行。
- 升级指南：
- 一级标准不支持插件代码兼容和 API 的二进制兼容。升级 Server 时，插件和 API 的二进制库文件必须升级，API 客户端需要重编，插件脚本可能需要修改；
- 数据库文件格式可能有变，如要确保能回退，升级前必须安全关机以保证所有的 redo log 都已经回收 。
二级兼容性标准实现全面向后兼容。要求 DolphinDB Server 满足一级兼容性标准，且在此基础上，兼容旧版本的全部函数和脚本；实现插件和 SDK 的代码兼容，插件在升级二进制文件后，用插件写的脚本能继续运行。
- 具体要求包括：
- 兼容旧版本的配置；
- 兼容旧版本的函数和脚本；
- 兼容旧版本的存储数据，包括分布式表数据，持久化的流表数据，定时任务，函数视图和用户权限数据等；
- 插件满足代码兼容性，即插件的二进制文件需要升级，但调用插件的脚本不需要修改；
- SDK 满足代码兼容性，客户端代码只要用新的 SDK 进行编译和链接，就可以连接新版本的服务器。
- 升级指南：
- 升级时，插件的二进制库文件可能需要升级；
- 数据库文件格式可能有变，如要确保能回退，升级前必须安全关机以保证所有的 redo log 都已经回收 。
三级兼容性标准在二级兼容性标准的基础上，实现插件和 SDK 的二进制兼容。
具体要求包括：
- 兼容旧版本的配置；
- 兼容旧版本的函数和脚本；
- 兼容旧版本的存储数据，包括分布式表数据，持久化的流表数据，定时任务，函数视图和用户权限数据等；
- 插件和 SDK 满足二进制兼容性，即插件和 SDK 不需要升级也能继续运行。
升级指南：
升级前必须做好控制节点和数据节点的元数据备份。回退时需要先恢复备份的旧版本的元数据。
四级兼容性标准在三级兼容性标准的基础上，要求新版本能够有条件回退到旧版本，并支持滚动升级，即 DolphinDB 集群可以逐一按节点进行升级，一个节点更新版本并稳定运行后，再升级集群内另一个节点。在升级过程中，如果出现异常，也可快速回退到旧版本，大幅降低升级风险。
支持滚动升级，内存中的数据格式、传输协议等需要完全兼容。
具体要求包括：
- 兼容旧版本的配置；
- 兼容旧版本的函数和脚本；
- 兼容旧版本的存储数据，包括分布式表数据，持久化的流表数据，定时任务，函数视图和用户权限数据等；
- 插件和 SDK 满足二进制兼容性，即插件和 SDK 不需要升级也能继续运行；
- 支持有条件回退。若新版本的存储数据未写入，版本能回退到旧版本继续运行。
- 兼容旧版本的内存数据，包括内存表的数据，矩阵、向量等变量的数据，以及传输协议等，确保集群的各节点能滚动升级。
五级兼容性标准是 DolphinDB 服务器的最高等级的兼容性标准，支持滚动升级，支持无条件回退到旧版本。
具体要求包括：
- 兼容旧版本的配置；
- 兼容旧版本的函数和脚本；
- 兼容旧版本的存储数据，包括分布式表数据，持久化的流表数据，定时任务，函数视图和用户权限数据等；
- 插件和 SDK 满足二进制兼容性，即插件和 SDK 不需要升级也能继续运行；
- 兼容旧版本的内存数据，包括内存表的数据，矩阵、向量等变量的数据，以及传输协议等，确保集群的各节点能滚动升级；
- 支持无条件回退到旧版本，即升级后，存储数据已写入新版本数据库，软件也能回退到旧版本继续运行，并为客户端正常提供服务。
各等级需要满足的兼容性要素如下表所示。
| 配置 | 函数和脚本 | 存储数据 | 插件 | SDK | 滚动升级 | 版本回退 | |
|---|---|---|---|---|---|---|---|
| 一级标准 | 兼容 | 可能删除声明 deprecation 超过一年的内置函数 | 向后兼容 | 代码可能不兼容 | 代码兼容 | 可能不支持 | 安全关机后回退 |
| 二级标准 | 兼容 | 兼容 | 向后兼容 | 代码兼容 | 代码兼容 | 可能不支持 | 安全关机后回退 |
| 三级标准 | 兼容 | 兼容 | 向前兼容 | 无需更新 | 无需更新 | 可能不支持 | 备份元数据后回退 |
| 四级标准 | 兼容 | 兼容 | 向前兼容 | 无需更新 | 无需更新 | 支持 | 备份元数据后回退 |
| 五级标准 | 兼容 | 兼容 | 向前兼容 | 无需更新 | 无需更新 | 支持 | 无条件回退 |
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 的技术支持工程师，进行风险评估。