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及之后。

性能调优

导入性能优化

1. 命令行选项调优：

• 宽表或者列值较长，将--batch选项的参数值调小。
• 索引会影响数据导入的性能。除主键和唯一键以外，普通索引延迟到数据导入结束后再创建。
• 机器的负载和网络都较低时，视情况可调整--thread选项的参数值。

2. 虚拟机参数调优：将导入脚本中的虚拟机参数修改为可用物理内存的60%。默认值为-Xms4G -Xmx4G。

vim bin/obloader
JAVA_OPTS="$JAVA_OPTS -server -Xms4G -Xmx4G -XX：MetaspaceSize=128M -XX：MaxMetaspaceSize=128M -Xss352K"

3. 数据库内核调优：导入数据的性能会严重受到租户的增量内存写入速度的影响。

• 增量内存不足时，数据库会触发合并或者转储。合并比较泪消耗性能，尽量不要触发。
• 增量内存使用率达到租户限速阈值时，导入性能同时会下降。
• 增量内存使用率已满时，数据很容易导入失败。建议租户限速的阈值高于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;

导出性能优化

1. 命令行选项调优：

• --thread：导出线程的并发数，根据数据库系统资源的利用情况进行调整。默认值为CPU * 2。
• --page-size：指定任务分片的大小，根据数据库系统资源的利用情况进行调整。默认值为1000000。

2. 虚拟机参数调优：将导出脚本中的虚拟机参数修改为可用物理内存的60%。默认值为`-Xms4G -Xmx4G 。

vim bin/obdumper
JAVA_OPTS="$JAVA_OPTS -server -Xms4G -Xmx4G -XX：MetaspaaceSize=128M -XX：MaxMetaspaceSize=128M -Xss352K

3. 数据库内核调优：要求导出一致性数据时，建议在导出数据前，手动触发一次合并，在合并成功后再重新导出数据。

数据处理

控制文件

定义控制文件：

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 列的值进行数值验证，非数值则返回 0
  c8 "replace(c8,'a','A')" map(8),                                                                  -- c8 列的值中的 a 替换为 A
  c9 "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 列的值不作任何处理，仅返回常量 1
  c18 "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