OBLoader和OBDumper導數工具介紹
- 使用指南
- 產品功能
- 使用須知
- 使用示例
- 旁路導入
- 性能調優
- 導入性能優化
- 導出性能優化
- 數據處理
- 控制文件
- 預處理函數
- 條件表達式
- 注意事項
使用指南
產品功能
🐘 OBLOADER是什么：
- Java語言開發的客戶端工具，僅適用于OceanBase數據庫。
- 將存儲介質中的數據庫對象的定義文件和表數據文件導入到OCceanBase數據庫中。
- 兼容mysqldump、Mydumper等客戶端工具導出的CSV格式的文件。
- OBLOADER專門優化了數據的導入性能，內置多種數據預處理函數又，自動容錯保證數據導入的穩定性，以及提供較為豐富的監控信息，以便于用戶實時觀測到數據文件導入的性能和進度。
🐘 產品功能：
- 支持從本地磁盤、Apache Hadoop、Aliyun OSS或者AmazzonS3導入數據庫對象定義和表數據。
- 支持導入mysqldump導出的SQL-Format格式的文件。
- 支持導入標準的CSV、InsertSQL、ORC、Parquet等格式的數據文件。
- 支持豐富的數據清洗功能。
- 支持多種錯誤處理策略。
- 支持在導入前邏輯切分原始數據文件，從而充分發揮CPU多核性能。
- 支持對命令行中指定的敏感參數進行加密。包括數據庫的賬號密碼、云存儲的賬號密鑰。
🦁 OBDUMPER是什么：
- Java語言開發的客戶端工具。僅適用于OceanBase數據庫。
- 可以使用該工具將OceanBase數據庫中定義的對象和表數據居以指定的文件格式導出到存儲介質中。
- 如果用戶希望借助于OBDUMPER進行邏輯備份，可以直接將該工具集成到數據庫運維系統中（不支持增量備份）。
- 與mysqldump等客戶端導出工具相比，OBDUMPER具備以下顯著的優勢：
- 快速的數據導出能力，設計了多種數據查詢策略，大幅提升導導出的性能。
- 豐富的數據交換能力，支持將表中數據以多種格式導出到多和中存儲介質。
- 強大的數據處理能力，導出前對數據進行壓縮、加密、脫敏、預處理等。
🦁 產品功能：
- 支持導出數據庫對象定義和表數據到本地磁盤、Aliyun OSS和Amaazon S3。
- 支持將表中的數據按照CSV、InsertSQL、ORC、Parquet等格式導出到文件中。
- 支持指定分區名，僅導出指定的表分區內的數據。
- 支持指定全局的過濾條件，僅導出滿足條件的數據。
- 支持配置數據預處理規則，導出前對數據進行轉換、脫敏等預處理。
- 支持指定SCN或者TIMESTAMP，僅導出有效事務點或者時間點的歷歷史快照數據。
- 支持從OceanBase的備副本中導出數據（區別于備集群）。
- 支持指定自定義的查詢語句，僅導出該查詢語句的結果集。
- 支持通過最新的快照版本以不鎖表的方式導出全局一致的數據。
- 支持對命令行中指定的敏感參數進行加密。包括數據庫的賬號密碼、云存儲的賬號密鑰。
使用須知
運行環境要求：
- 系統版本：支持Linux/macOS/Windows7及之后版本。
- Java環境：請安裝
Oracle JDK 1.8.0_3xx，配置JAVA_HOME環境變量。 - 字符集：推薦使用UTF-8文件編碼。
- JVM參數：請編輯
bin/obloader和bin/obdumper腳本修改JVM內存參數，避免出現JVM內存不足。
OBLOADER運行權限要求：
- 使用OBLOADER連接OceanBase數據庫導入數據時，連接數據庫的賬號需要擁有
CREATE/SELECT/INSERT/UPDATE等命令的執行權限。 - 導入數據前，用戶需要擁有
oceanbase數據庫的查詢權限。
OBDUMPER運行權限要求：
- 使用OBDUMPER連接OceanBase數據庫導出數據庫導出數據時，連接數據庫的賬號需要擁有
CREATE/SELECT等命令的執行權限。 - 導出數據前，用戶需要擁有
oceanbase數據庫的查詢權限。
- 下載地址：www.oceanbase.com/softwarecenter
- 安裝包：ob-loader-dumper-4.3.3.1-RELEAE.zip
使用示例
obloader和obdumper命令行選項分為基礎選項和高級選項。
- 基礎選項：常用選項，包括連接選項(連接數據庫模式)、功能選選項（文件格式、數據庫對象類型、存儲路徑）和其它選項。
- 高級選項：包括功能選項（時間戳格式、表/列黑白名單篩選、錯誤處理）和性能選項。
OBLOADER導入示例：
./obloader -h xx.x.x.x -P 2883 -u test@mysql#cluster_a -p ****** -D USERA --csv --table '*' -f /output
其中，-h/-P/-u/-p/-D為數據庫連接選項；--csv為文件格式選項；--table為數據庫對象類型選項；-f為存儲路徑。
OBDUMPER導出示例：
./obdumper -h xx.x.x.x -P 2883 -u test@mysql#cluster_a -p ****** -D USERA --csv --table '*' -f /output
其中，-h/-P/-u/-p/-D為數據庫連接選項；--csv為文件格式選項；--table為數據庫對象類型選項；-f為存儲路徑。
旁路導入
OBLOADER v4.2.6及之后的版本支持旁路導入數據。
旁路導入重點參數：
--direct：用于指定旁路導入模式。該選項與--rpc-port和--parallel搭配使用。--rpc-port=rpc_port_num：用于連接OBServer RPC端口。該選項與--direct和--parallel搭配使用，表示在旁路導入模式下連接OBServer RPC端口導，入數據。--parallel= parallel_num：用于旁路導入時加載數據的并行度。該選項與--rpc-port和--direct搭配使用。
注意事項：
- OBLOADER旁路導入模式暫時不支持二進制數據類型。
- OBLOADER旁路導入模式支持連接OBServer和ODP。對應的版本要求：
- 連接OBServer時：要求OBServer版本必須為4.2.0及之后。
- 連接ODP時：要求ODP版本必須為4.1.3及之后，且OBServer版本必須為4.2.1及之后。
性能調優
導入性能優化
- 命令行選項調優：
- 寬表或者列值較長，將
--batch選項的參數值調小。 - 索引會影響數據導入的性能。除主鍵和唯一鍵以外，普通索引延遲到數據導入結束后再創建。
- 機器的負載和網絡都較低時，視情況可調整
--thread選項的參數值。
- 虛擬機參數調優：將導入腳本中的虛擬機參數修改為可用物理內存的60%。默認值為
-Xms4G -Xmx4G。
vim bin/obloader
JAVA_OPTS="$JAVA_OPTS -server -Xms4G -Xmx4G -XX：MetaspaceSize=128M -XX：MaxMetaspaceSize=128M -Xss352K"
- 數據庫內核調優：導入數據的性能會嚴重受到租戶的增量內存寫入速度的影響。
- 增量內存不足時，數據庫會觸發合并或者轉儲。合并比較淚消耗性能，盡量不要觸發。
- 增量內存使用率達到租戶限速閾值時，導入性能同時會下降。
- 增量內存使用率已滿時，數據很容易導入失敗。建議租戶限速的閾值高于90。轉儲相關參數的設置跟租戶內存的大小、寫入速度都有關系，需根據實際情況進行調優。內核相關的調優參數如下所示。
--SQL中過程中的內存占用百分比。默認值為5
set global ob_sql_work_area_percentage=20;--服務端可接收的最大的網絡數據包大小
set global max_allowed_packet=1073741824;--用于設置觸發全局凍結的租戶內存使用閾值。v4.x默認值為20
alter system set freeze_trigger_percentage=30;--用于控制分層轉儲觸發向下一層的下壓的閾值。默認值為2
alter system set minor_compact_trigger=16;--服務端的內存限流閾值。默認值為60，設置為100表示不做限流
alter system set writing_throttling_trigger_percentage=100;
導出性能優化
- 命令行選項調優：
--thread：導出線程的并發數，根據數據庫系統資源的利用情況進行調整。默認值為CPU * 2。--page-size：指定任務分片的大小，根據數據庫系統資源的利用情況進行調整。默認值為1000000。
- 虛擬機參數調優：將導出腳本中的虛擬機參數修改為可用物理內存的60%。默認值為`-Xms4G -Xmx4G 。
vim bin/obdumper
JAVA_OPTS="$JAVA_OPTS -server -Xms4G -Xmx4G -XX：MetaspaaceSize=128M -XX：MaxMetaspaceSize=128M -Xss352K
- 數據庫內核調優：要求導出一致性數據時，建議在導出數據前，手動觸發一次合并，在合并成功后再重新導出數據。
數據處理
控制文件
定義控制文件：
lang=java
(
列名 字節偏移位置(可選) "預處理函數"(可選) 映射定義(可選),
列名 字節偏移位置(可選) "預處理函數"(可選) 映射定義(可選),
列名 字節偏移位置(可選) "預處理函數"(可選) 映射定義(可選),
列名 字節偏移位置(可選) "預處理函數"(可選) 映射定義(可選)
);
- 列名：數據庫表結構中的字段名稱。OBLOADER不區分列名大小寫。果需要區分大小寫，請將列名放入中括號([])或者反引號(``)內。例如：
[c1]表示c1列，[C1]表示C1列。 - 字節偏移位置：支持兩種聲明方式，絕對偏移和相對偏移。僅
--pos格式數據支持定義字節偏移位置。- 絕對偏移：
position(start,end)，start與end分別表示字段的起始位置置（字節）與結束位置（字節）。如果需要指定列長以忽略導入某一段字節到數據庫表中，可以使用特殊關鍵字_FILLER代替實際的列名并標記該部分數據，此操作將創建一個匿名列，該列會由OBLOADER解析，但不會與表中的任何現有列關聯。此關鍵字特別適用于忽略文件中某些不相關的數據，如行尾的填充字節。示例：_filler position(5:10)，表示跳過第5到第10個字節。 - 相對偏移：
position(length)，length表示字段的長度（字節）。
- 絕對偏移：
- 預處理函數：在控制文件中為指定的列配置預處理函數，以對導入的數據進行預處理。
- 映射定義：導入的數據文件中預處理數據的列位置。
注意：
- 控制文件的命名規范為
<表名>.ctrl。 - 一個控制文件對應一個表，預處理多個表的數據時，需要在
ctl-path路徑下創建多個控制文件，且控制文件名須與導入的對應表名相同。 - 通過
--ctl-path選項指定控制文件所在的絕對路徑。
預處理函數
定義控制文件時，用戶可以為每一個列配置對應的預處理函數。
注意事項：
- 任何預處理函數的形式參數中只能引用當前列的值，暫不支持跨列引用。例如：不支持
c14 "concat(c15,'_suffix')"，僅支持c15 "concat(c15,'_suffix')"。 - 預處理函數
LPADB()和RPADB()適用于字母、數字和中文等字符，處理Emoji表情符號時可能會出現截斷。 - 預處理函數
REPLACE()在導數工具中的表現不同于在Oracle和MySQL中。其語法上更接近Oracle，實現上更接近MySQL。 - 預處理函數
NVL()參考了MySQL中對應的內置函數，它在實現上是區分了空字符和NULL。 - 與日期時間相關的預處理函數（
SYSTIMESTAMP、TMSFMT()和TO_TIMESTAMP()等）只能精確到毫秒。此外，要求工具運行的服務器時鐘與數據庫服務器時鐘相同。 - 預處理函數
LPAD(char,length[,pad_string])和RPAD(char,length[,pad_string])參考了MySQL中對應的內置函數。參數length是最終顯示在終端上的返回值的總長度。在大多數字符集中，這會是返回值中的字符數。但是，在某些多字節字符集中，字符串的顯示長度可能與字符串中實際的字符數不不同，所以此函數在處理多字節值時是不安全的。
條件表達式
定義控制文件時，可使用條件表達式進行簡單的邏輯運算和算術運算以實現更復雜的數據處理能力。
條件表達式語法：
--Simple Case表達式
CASE <expr> WHEN <constant> THEN [constant | expr] ELSE [constant | expr] END;--Search Case表達式
CASE WHEN <condition> THEN [constant | expr] ELSE [constant | expr] END;
參數為條件運算表達式：
is [not] null # 空/非空判斷
not <condition> # 真值條件表達式的取反運算
[not] in (string_list) # 關系判斷
數據處理示例：
lang=java
(c1 "lower(c1)" map(1), -- c1 列的值中的字母轉換為小寫c2 "ltrim(c2)" map(2), -- c2 列的值從左開始截斷空格c3 "rtrim(c3)" map(3), -- c3 列的值從右開始截斷空格c4 "substr(c4,0,5)" map(4), -- c4 列的值第 1 位置截取 5 個字符長度的字符串c5 "trim(c5)" map(5), -- c5 列的值左右兩側截斷空格c6 "upper(c6)" map(6), -- c6 列的值中的字母轉換為大寫c7 "nanvl(c7,'0')" map(7), -- c7 列的值進行數值驗證，非數值則返回 0c8 "replace(c8,'a','A')" map(8), -- c8 列的值中的 a 替換為 Ac9 "nvl(c9,'null')" map(9), -- c9 列的值進行判空，若為 null 返回 null 字符串c10 "length(c10)" map(10), -- c10 列的值進行長度計算c11 "lpad(c11,5,'x')" map(11), -- c11 列的值左側追加 5 個字節長度字符串 'x'c12 "rpad(c12,5,'x')" map(12), -- c12 列的值右側追加 5 個字節長度字符串 'x'c13 "convert(c13,'utf-8','gbk')" map(13), -- c13 列的值從 gbk 轉換為 utf-8 字符編碼c14 "concat(c14, '_suffix')" map(14), -- c14 列的值與常量進行拼接c15 "none" map(15), -- c15 列的值不作任何處理，直接返回對應列的值c16 "systimestamp" map(16), -- c16 列的值不作任何處理，直接返回當前集群的時間戳c17 "constant('1')" map(17), -- c17 列的值不作任何處理，僅返回常量 1c18 "lpadb(c18,5,'x')" map(18), -- c18 列的值左側追加 5 個字節長度的(單)字符 'x'c19 "rpadb(c19,5,'x')" map(19), -- c19 列的值右側追加 5 個字節長度的(單)字符 'x'c20 "case when length(trim(c20))<18 then 'Y' else 'N' end" map(20), -- c20 列的值進行條件真值匹配，若為真返回對應列的值c21 "case length(trim(c21)) when '1' then 'one' when '2' then 'two' else 'unknown' end" map(21), -- c21 列的值進行條件等值匹配，若匹配成功返回對應列的值C22 "SYSDATE" map(22), -- c22 列的值為當前日期C23 "MASK(C23)" map(23), -- c23 列的值進行脫敏，只對列名有效，列中的大、小寫字母和數字使用默認脫敏字符替代（默認脫敏字符：大寫字母 X，小寫字母 x，數字 n）C24 "MASK_FIRST_N(C24,'A','a','b',3)" map(24), -- c24 列的值指定大、小寫字母以及數字的脫敏字符（默認 N 為 0，從第一個字符開始）C25 "MASK_LAST_N(C25,'A','a','b',3)" map(25), -- c25 列的值指定大、小寫字母以及數字的脫敏字符（默認 N 為 0，從最后一個字符開始）C26 "MASK_SHOW_FIRST_N(C26,'A','a','b',3)" map(26), -- c26 列的值指定不脫敏字符數（默認 N 為 0，從第一個字符開始）C27 "MASK_SHOW_LAST_N(C27,'A','a','b',3)" map(27), -- c27 列的值指定不脫敏字符數（默認 N 為 0，從最后一個字符開始）C28 "REVERSE(C28)" map(28), -- c28 列的值將字符順序顛倒
);
注意事項
- 標準的CSV格式請參考RFC 4180規范，建議導入時嚴格遵從RFC 4180規范。
- 導入導出大量數據時，請在運行的腳本中修改JAVA虛擬機的內存參數以便于提升性能。
- 命令行參數指定的對象名、數據文件名、規則文件名要求大小寫一致。MySQL默認小寫。如果需要區分大小寫，請將表名放入中括號內。例如：
--table'[test]'表示test表，文件名格式為test.group.sequence.suffix；--table [TEST]表示TEST表，文件名格式為TEST.group.sequence.suffix。- 其中，
group表示子任務號（由程序依子任務切分策略決定），sequence表示文件滾動號（當文件大小超過--block-size，則會發生滾動），suffix表示文件拓展名。
- 導入時，OBLOADER可以識別的文件名格式為：
"表名"+文件拓展名。可以使用--file-regular-expression命令行選項，通過正則表達式實現自定義的文件檢索規則。 - 數據庫對象存在依賴（如表間外鍵依賴、觸發器對序列的依賴等）時，請盡可能按依賴順序依次導入。如果通過
--all或者--table '*'導入，則無法嚴格保證導入順序。 - 無主鍵的表，暫不支持斷點續傳。
- OceanBase 3.2.4及之后的版本使用OBLOADER前，請將系統配置項
open_cursors設置為較大的值，否則導入可能會出現錯誤。數據導入結束后，請將該系統配置項重置成初始值。例如：ALTER SYSTEM SET open_cursors=65535;。 - 導入DDL時，請區分
--mix與--ddl選項。--ddl選項適用于導入包含僅有一條DDL語句的文件，而--mix選項無此限制。 - OBLOADER支持的文件格式如下：
- DDL文件：文件中的內容僅包含DDL語句，不包含表數據。
- CSV文件：符合RFC 4180規范的標準CSV格式。
- SQL文件：文件中的內容僅包含INSERT SQL語句，數據不換行。
- ORC文件：符合標準的Apache ORC的格式，默認使用zstd壓縮。
- Parquet文件：符合標準的Apache Parquet的格式，默認使用zstd壓縮。
- MIX文件：文件中的內容包含DDL語句、DML語句等任意符合合SQL標準的語句。
- POS文件：以固定字節長度定義的格式，暫不支持固定字符長度。
- CUT文件：數據列使用單字符或多字符進行分隔、且不帶定界符。別于標準的CSV格式。
References
【1】https://www.oceanbase.com/docs/common-oceanbase-dumper-loader-1000000002781937
