DolphinDB 版本相容性標準

語言: CN / TW / HK

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 的技術支援工程師,進行風險評估。