乾貨丨DolphinDB啟動指令碼教程
技術標籤:時序資料庫使用教程DolphinDB時序資料庫分散式系統大資料分析資料庫開發
DolphinDB database從1.0版本開始,提供了啟動指令碼功能。使用者可以通過配置引數startup來指定使用者級的啟動指令碼,預設值是startup.dos。通過設定啟動指令碼,DolphinDB啟動的時候會自動完成每次啟動都需要執行的工作,譬如初始化流資料,定義共享變數,載入外掛指令碼等。
1. DolphinDB啟動順序
DolphinDB節點的啟動是一個複雜的過程。與啟動指令碼相關的指令碼和任務至少包括:系統級的初始化指令碼(通過init引數指定,預設值dolphindb.dos),函式檢視(function view)以及定時任務(scheduled job)。啟動指令碼以及相關元件資源的初始化順序如下圖所示。
啟動指令碼以及相關元件資源的初始化順序
系統級初始化指令碼是必需的,預設是版本釋出目錄中的dolphindb.dos,其中定義了一些系統級的函式。從啟動順序圖中我們可以看到,dolphindb.dos指令碼在執行時指令碼直譯器、工作執行緒等已完成初始化,但系統的網路和分散式檔案系統尚未啟動、函式檢視尚未載入。而啟動指令碼執行前,系統的網路和分散式檔案系統已啟動,函式檢視已載入。因此在啟動指令碼中我們幾乎可以做任何事情。
從圖中也可以看到使用者事先安排的定時任務在啟動指令碼執行後加載。因此scheduled jobs中若用到了外掛函式、共享表等,需要在啟動指令碼中預先載入或定義,否則反序列化scheduled job會失敗。需要注意的是,函式檢視的載入在啟動指令碼執行之前。如果函式檢視中用了外掛,載入外掛必須在dolphindb.dos中完成。與定時任務儲存在資料節點不同,函式檢視儲存在控制節點。所以我們不建議在函式檢視中使用外掛,否則在叢集中每個節點的dolphindb.dos都需要載入外掛。
2. 啟動指令碼的執行
啟動指令碼的配置項名為startup,引數值是自定義的啟動指令碼檔名,可配置絕對路徑或相對路徑,引數的預設值是startup.dos。若配置了相對路徑或者沒有指定目錄,系統會在節點的home目錄、工作目錄和可執行檔案所在目錄依次搜尋。該引數單機模式時在dolphindb.cfg中配置,叢集模式時在節點配置檔案cluster.cfg中配置。
配置舉例如下:
startup=/home/streamtest/init/server/startup.dos
啟動指令碼以本地管理員的身份執行,但並沒有登入叢集,所以訪問叢集的分散式功能時以guest身份執行。因此,若要遠端執行控制節點的某些功能,訪問叢集中的某個分散式表,需要先以管理員(admin)或其他授權使用者身份登入。具體可以通過login
指令碼執行過程中若遇到錯誤,執行會中斷,但系統不會退出,而是繼續執行。執行過程中的所有輸出,都會記錄在本地節點的日誌檔案中。
3.啟動指令碼的常見應用場景
系統重啟後可能需要做的初始化工作主要有:定義並共享記憶體表,定義、載入並共享流資料表、訂閱流資料、載入外掛等。
例子1:定義記憶體表並共享
下面程式碼中定義了一張記憶體表t,並分享為sharedT。在其他會話中就可以對錶sharedT進行增加、更新、刪除和查詢記錄。
t=table(1:0,`date`sym`val,[DATE,SYMBOL,INT])
share(t, `sharedT);
例子2:定義、載入流資料表並共享、訂閱
流資料表的定義不可在DolphinDB中持久化儲存,所以流資料表的初始化工作可在啟動指令碼中執行。下面程式碼載入並共享了流資料表st1:
login("admin","123456")
t1=streamTable(1:0,`date`sym`val,[DATE,SYMBOL,INT])
enableTableShareAndPersistence(table=t1,tableName=`st1,cacheSize=1000)
流資料表的訂閱也可在啟動指令碼中完成。下面的程式碼訂閱了上述流資料表st1,並把訂閱的資料儲存到分散式庫表:
tb=loadTable("dfs://db1","tb")
subscribeTable(,"st1","subst",-1,append!{tb},true)
例子3:載入外掛
若scheduled jobs中用到了外掛函式,必須在啟動指令碼中載入外掛,否則會因反序列化失敗導致系統退出。下列程式碼在scheduled jobs中用到了odbc外掛:
use odbc
def jobDemo(){
conn = odbc::connect("dsn=mysql_factorDBURL");
//...
}
scheduleJob("job demo","example of init",jobDemo,15:48m, 2019.01.01, 2020.12.31, 'D')
但odbc外掛在系統啟動時沒有載入,所以讀取scheduled job的時候,因無法識別這個函式,輸出下列日誌後退出系統。
<ERROR>:Failed to unmarshall the job [job demo]. Failed to deserialize assign statement.. Invalid message format
在啟動指令碼中加入下列程式碼載入odbc外掛後,系統即啟動成功。
loadPlugin("plugins/odbc/odbc.cfg")
4. 啟動指令碼的編寫
編寫DolphinDB啟動指令碼時,可以使用module來宣告和使用可重用模組,可以自定義函式,可以使用分散式的功能。幾乎沒有限制。
若需要除錯啟動指令碼,可以在指令碼中用print
與writeLog
等函式列印日誌。系統會把啟動指令碼執行情況輸出到節點日誌,譬如一開始系統會輸出下列日誌表示啟動指令碼開始執行:
<INFO> :Executing the startup script:
編寫啟動指令碼時,為了防止出現異常而停止執行後續的指令碼,可使用try-catch語句俘獲異常。
5. 啟動指令碼不適用的場景
啟動指令碼幾乎可以做任何事情,但是少數功能和任務仍然不適合在啟動指令碼中完成。
- 定時任務在啟動指令碼之後執行,所以不能在啟動指令碼中使用跟定時任務相關的任何功能,包括函式
scheduleJob
,getScheduledJobs
和deleteScheduledJob
。 - 若需要定義系統級的函式,所有使用者都能看到,而且不能被覆蓋,請在初始化指令碼dolphindb.dos中定義。
- 若任務需要依賴其他節點,不適合在啟動指令碼中完成,極有可能因為其他節點尚未啟動而導致不能執行任務。