命令行选项

OBLOADER 通过命令行选项指定导入所需要的信息，更多选项描述和使用示例，请参考 选项列表 与 使用示例。

选项介绍

选项风格

OBLOADER 参数设计采用 Unix 和 GNU 两种风格方式。

• Unix 风格的参数前加单破折线，选项为单字符，例如：ps -e；该风格的选项和参数之间可以不加空格，例如：-p******。

• GNU 风格的长参数前加双破折线，选项为单字符或者字符串，例如：ps --version；要求选项和参数之间有空格，例如：--table 'test'。

选项分类

OBLOADER 命令行选项分为基础选项和高级选项。

• 基础选项：OBLOADER 常用选项，包括连接选项（连接数据库模式）、功能选项（文件格式、数据库对象类型、存储路径）和其它选项。

• 高级选项：包括功能选项（时间戳格式、表/列黑白名单筛选、错误处理）、性能选项和其它选项。

必选选项

使用 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 为存储路径。

基础选项

连接选项

OBLOADER 需连接 OceanBase 数据库才可读写数据。用户指定以下选项可以连接到 OceanBase 数据库。

导入类型

旁路导入

OBLOADER 4.2.6 及之后的版本支持旁路导入数据。

• --rpc-port= rpc_port_num

  用于连接 OBServer RPC 端口。该选项与 --direct, --parallel 搭配使用，表示在旁路导入模式下连接 OBServer RPC 端口导入数据。

  说明

  • 该选项仅适用于 OceanBase 4.2.0 RC2 及之后的版本。
  • 获取 OBServer RPC 端口方式：
    • 连接 ODP 服务端时：
      • 云数据库 OceanBase 环境下，ODP RPC Port 默认 3307。
      • OceanBase 数据库环境下，默认端口 2885；如果需要自定义，可以在启动 ODP 时通过 -s 选项进行指定。
    • 连接 OBServer 服务端时，sys 租户下查询系统视图 DBA_OB_SERVERS 即可获取 OBServer 的 RPC 端口，默认端口 2882。

• --direct

  用于指定旁路导入模式。该选项与 --rpc-port, --parallel 搭配使用。

  说明

  • OBLOADER 旁路导入模式暂时不支持二进制数据类型。
  • OBLOADER 旁路导入模式支持连接 OBServer 和 ODP。对应的版本要求：
    • 连接 OBServer 时：要求 OBServer 版本必须为 4.2.0 及之后。
    • 连接 ODP 时：要求 ODP 版本必须为 4.1.3 及之后， 且 OBServer 版本必须为 4.2.1 及之后。

• --parallel= parallel_num

  用于旁路导入时加载数据的并行度。该选项与 --rpc-port, --direct 搭配使用。

功能选项

文件格式

数据库对象类型

• --all

  用于标识导入所有已支持的数据库对象定义和表数据。该选项与 --ddl 搭配使用时，表示导入所有的数据库对象定义文件；该选项与--csv, --sql, --cut, --pos 任意一种数据格式选项搭配使用时，表示导入所有对应格式的数据文件。如果需要导入所有的数据库对象定义和表数据，可指定 --all, --ddl 选项再搭配任意一种数据格式选项。

  说明

  --all 选项与任意的数据库对象选项之间都是互斥的，不可同时指定；如果同时指定 --all 选项与任意的数据库对象选项，则会优先执行 --all 选项命令。

• --table-group 'table_group_name [,table_group_name...]' | --table-group '*'

  用于标识导入 表组 定义。除了不支持导入数据外，其它描述同 --table 选项。

• --table 'table_name [,table_name...]' | --table '*'

  用于标识导入表定义或者表数据。该选项与 --ddl 搭配使用时，表示仅导入表定义；该选项与任意一种数据格式选项搭配使用时，表示仅导入表数据。指定多个表时，表名用逗号分隔（,）。导入 OceanBase Oracle 模式租户的表名默认按照大写处理，导入 OceanBase MySQL 模式租户的表名默认按照小写处理；例如：OceanBase Oracle 模式下，--table 'test' 和 --table 'TEST' 均表示 TEST 表；OceanBase MySQL 模式下，--table 'test' 和 --table 'TEST' 均表示 test 表。如果需要区分大小写，请将表名放入中括号内（[ ]）。例如：--table '[test]' 表示 test 表，--table '[TEST]' 表示 TEST 表。如果表名指定为星号（*），表示导入所有的表定义或者表数据。

  注意

  导入使用控制文件时，如果 --table 指定的指定的表名大小写必须和数据库中保持一致，否则控制文件无法生效。

• --view 'view_name [, view_name...]' | --view '*'

  用于标识导入 视图 定义。除了不支持导入数据外，其它描述同 --table 选项。

• --trigger 'trigger_name [, trigger_name...]' | --trigger '*'

  用于标识导入 触发器 定义。除了不支持导入数据外，其它描述同 --table 选项。

• --sequence 'sequence_name [, sequence_name...]' | --sequence '*'

  用于标识导入 序列 定义。除了不支持导入数据外，其它描述同 --table 选项。目前仅适用于 OceanBase Oracle 模式。

• --synonym 'synonym_name [, synonym_name...]' | --synonym '*'

  用于标识导入 同义词 定义。除了不支持导入数据外，其它描述同 --table 选项。目前仅适用于 OceanBase Oracle 模式。

• --type 'type_name [, type_name...]' | --type '*'

  用于标识导入 类型 定义。除了不支持导入数据外，其它描述同 --table 选项。仅适用于 OceanBase Oracle 模式。

• --type-body 'typebody_name [, typebody_name...]' | --type-body '*'

  用于标识导入 类型体 定义。除了不支持导入数据外，其它描述同 --table 选项。仅适用于 OceanBase Oracle 模式。

• --package 'package_name [, package_name...]' | --package '*'

  用于标识导入 包 定义。除了不支持导入数据外，其它描述同 --table 选项。仅适用于 OceanBase Oracle 模式。

• --package-body 'packagebody_name [, packagebody_name...]' | --package-body '*'

  用于标识导入 包体 定义。除了不支持导入数据外，其它描述同 --table 选项。仅适用于 OceanBase Oracle 模式。

• --function 'function_name [, function_name...]' | --function '*'

  用于标识导入 函数 定义。除了不支持导入数据外，其它描述同 --table 选项。

• --procedure 'procedure_name [, procedure_name...]' | --procedure '*'

  用于标识导入 存储过程 定义。除了不支持导入数据外，其它描述同 --table 选项。

存储路径

• -f 'file_path', --file-path= 'file_path'

  用于指定数据文件存放在本地磁盘的绝对路径。从 Aliyun OSS 导入数据文件时亦需要指定 -f 选项，以保存生成的日志和二进制文件。

• --storage-uri 'storage_uri_string'

  用于标识存储的统一资源定位符。OBLOADER 4.2.0 及之后的版本支持从 Aliyun OSS 或者 Amazon S3 导入数据库对象定义和表数据；OBLOADER 4.2.1 及之后的版本支持从 Hadoop 导入数据库对象定义和表数据。

  'storage_uri_string' 语法格式：

  [scheme://host]path[?parameters]
  
  parameters: key[=value],...
  

  组成部分说明：

  组成部分	说明
  scheme	支持的存储类型：Aliyun OSS/Amazon S3/Hadoop。 如果指定的 scheme 不是当前支持的 OSS/S3/Hadoop，则会报错。
  host	指定存储空间名称。 从 OSS/S3 导入数据时，host 指代存储桶，具体请参考 OSS Bucket。 从 Apache Hadoop 导入数据时，该项为 Hadoop 节点，满足格式：<ip>:<port> 或 <cluster_name>。
  path	指定从存储空间导入数据的资源路径。路径必须以 / 开头。
  parameters	指定请求所需的参数。 其中，parameters 可为单个 Key 或 Key-Value 对。

  示例：从 S3 导入数据

  --storage-uri 's3://bucket/path?region={region}&access-key={accessKey}&secret-key={secretKey}'
  

  • s3：scheme 为 s3。
  • bucket：S3 存储空间的名称。
  • path：从 S3 导入数据的资源路径。
  • ?region={region}&access-key={accessKey}&secret-key={secretKey}：指定 region, access-key, secret-key 参数值。

  支持的参数：

  参数	是否需要 value	说明	支持的存储类型	支持版本
  endpoint	是	用于指定 OSS host 所在地域的 Endpoint。 用于通过域名 Endpoin 访问 S3。	OSS S3	4.2.0 4.2.5
  region	是	用于指定终端节点，为 S3 bucket 所在的物理位置。	S3	4.2.0
  storage-class	是	用于指定 Amazon S3 存储类。	S3	4.2.0
  access-key	是	用于指定存储的访问账号。	OSS/S3	4.2.0
  secret-key	是	用于指定存储的访问密钥。	OSS/S3	4.2.0
  hdfs-site-file	是	用于指定 hdfsSiteFile 配置文件，其中包含 Apache Hadoop 的配置信息，以设置 Apache Hadoop 的存储和访问规则，例如块大小和副本数量。	Apache Hadoop	4.2.1
  core-site-file	是	用于指定 hdfsSiteFile 配置文件，其中包含 Hadoop 集群中的核心配置信息，例如 Apache Hadoop 文件系统的 URI 和默认文件系统。	Apache Hadoop	4.2.1
  principal	是	用于指定 Kerberos 中的身份验证标识符。	Apache Hadoop	4.2.1
  keytab-file	是	用于指定 Keytab 文件的绝对路径，以授权用户或服务访问系统的资源。	Apache Hadoop	4.2.1
  krb5-conf-file	是	用于指定 Kerberos 配置文件路径。	Apache Hadoop	4.2.1

  说明

  • 从 Aliyun OSS 导入数据库对象定义和表数据时，endpoint, access-key, secret-key 为必填参数。
  • 从 Amazon S3 导入数据库对象定义和表数据时，region, access-key, secret-key 为必填参数。

• --ctl-path 'control_path'

  用于指定控制文件存放在本地磁盘的绝对路径。控制文件中可配置内置的处理函数，数据导入前根据配置的函数对数据进行预处理。例如：大小写转换，判空等。有关控制文件的使用，请参考 数据处理 章节。命令行指定该选项时，需要在参数值前后加上单引号。例如：--ctl-path '/home/controls/'。

• --log-path 'log_path'

  指定 OBLOADER 运行日志的输出目录。命令行未指定该选项时，OBLOADER 运行日志默认会输出到 -f 选项指定的目录。没有特殊要求的情况下，无需使用重定向来输出日志。

其它选项

• -H, --help

  用于查看命令行工具的使用帮助。

• -V, --version

  用于查看当前发行的工具版本号。

高级选项

功能选项

时间戳格式

• --nls-date-format 'date-format-string'

  用于设置 OceanBase Oracle 模式下数据库连接中的日期格式。默认值：YYYY-MM-DD HH24:MI:SS。

• --nls-timestamp-format 'timestamp-format-string'

  用于设置 OceanBase Oracle 模式下数据库连接中的时间戳格式。默认值：YYYY-MM-DD HH24:MI:SS:FF9。

• --nls-timestamp-tz-format 'timestamp-tz-format-string'

  用于设置 OceanBase Oracle 模式下数据库连接中包含时区的时间戳格式。默认值：YYYY-MM-DD HH24:MI:SS:FF9 TZR。

黑白名单筛选

• 表黑白名单筛选

  • --exclude-table 'table_name [, table_name...]'

    用于表示导入表定义或者表数据时排除指定的表。表名支持模糊匹配。 使用示例：--exclude-table 'test1,test*,*test,te*st' 上述参数表示导入表定义或者表数据时排除以下符合条件的表：

    • test1

    • 所有的表名以 test 开头的表

    • 所有的表名以 test 结尾的表

    • 所有的表名以 te 开头且以 st 结尾的表

  • --exclude-data-types 'datatype [, datatype...]'

    用于表示导入数据时排除指定的数据类型。

  • --file-regular-expression

    用于导入单表文件时，根据指定的正则表达式选择性地导入指定的文件。该选项仅适用于单表导入。例如：--file-regular-expression ".*"，表示使用 ".*" 正则表达式匹配目录下的所有文件，* 表示匹配零个或多个任意字符；--file-regular-expression ".*\\.csv"，表示使用 ".*\.csv" 正则表达式匹配以 ".csv" 结尾的文件，其中 "\." 表示匹配实际的句点字符 "."。

• 列黑白名单筛选

  • --exclude-column-names 'column_name [, column_name...]'

    用于排除导入时指定的列名所对应的数据。

    注意

    • 指定的列名需要与表结构中的列名大小写保持一致。
    • 导入的数据文件中，被排除的列无对应的数据且被导入的列顺序与表中列顺序需要保持一致。

错误处理

• --max-discards int_num

  指定该选项可以限制每一张表的重复数据的最大值。如果任意一张表的重复数据超过最大值，则停止导入该表的数据，日志记录该表导入失败，不影响其它表导入。默认值：-1，表示忽略重复数据继续导入。

  说明

  表中包含主键或者唯一键且数据出现重复时，该选项才会生效。

• --retry

  用于标识导入任务从中断点进行重试。使用建议：如果导入的数据量已超过 80%，可指定该选项进行断点续传，避免重新导入（断点续传的过程中可能有少量的数据出现重复错误）；如果已经导入的数据量不多，可清空表重新开始导入，效率更高。

  注意

  • load.ckpt 文件是工具运行时生成的保存点文件，路径位于 -f 指定的目录中。如果 load.ckpt 文件不存在，无法使用该选项。
  • 该选项不适用于旁路导入。

• --max-errors int_num

  指定该选项可以限制每一张表导入时遇到错误数的最大值。如果任意一张表导入的错误数超过最大值，则停止导入该表的数据，日志记录该表导入失败。该选项可选的值分别是 0、-1 和正整数 N。指定参数值为 -1 时，表示忽略错误，继续导入。默认值：1000。

• --strict= 'strict_string'

  用于导入时控制脏数据对进程结束状态的影响。默认值：true，表示导入的数据中存在 Bad Record 或者 Discard Record 类型错误时会以失败状态结束程序（System exit 1）；false，表示导入的数据中存在 Bad Record 或者 Discard Record 类型错误时，不影响程序最终结束状态（System exit 0）。

  说明

  该选项可与 --max-discards 或者 --max-errors 选项搭配使用，表示当重复数据量或者错误数在指定范围内，会跳过错误继续进程。更多详情请参见 错误处理。

• --replace-data

  用于标识替换表中重复的数据。该选项仅适用于已定义主键或者是已定义唯一键（包含非空字段）的表。如果文件中重复的数据较多，占比超过总数据量 30% 以上，建议清理表重新导入。数据替换的性能低于空表导入的性能。该选项与 --csv, --sql, --cut 选项搭配使用，对 --ddl 选项不生效。

  注意

  • 文件和表中出现重复的数据时，表中的数据会被替换为文件中的数据。
  • 对于无主键或者无唯一键的表，该选项会在表中追加写入数据。
  • 用户不需要替换重复数据时，请勿在命令行中指定该选项，避免对业务造成影响。

性能选项

• --rw float_num

  用于标识文件解析线程占总线程数的比例。默认值：1。 该选项与 --thread 选项搭配使用，可计算出文件解析线程数等于 --thread 选项值 * --rw 选项值。

• --slow float_num

  用于标识工具进入慢导模式的阈值。当 OceanBase 内存占用达到 75% 时，OBLOADER 会自动降速，防止数据库内存占用持续飙升。默认值：0.75。

• --pause float_num

  用于标识工具进入停导模式。当 OceanBase 内存占用达到 85% 时，OBLOADER 会自动停止导入，防止数据库内存水位过高引发内存问题。默认值：0.85。

• --batch int_num

  用于标识批量写入的事务大小。建议该选项的值与表的宽度成反比的关系，但不可设置过大导致数据库内存溢出。默认值：200。

  说明

  OBLOADER 4.2.0 及之后的版本支持根据 JAVA 虚拟机的内存自适应 --batch 的默认值。

• --thread int_num

  用于标识并发线程数。该选项直接对应写入线程数。与 --rw 选项搭配使用时，用于计算文件解析线程数，计算公式：--thread 参数值 * --rw 参数值。默认值为 CPU 乘以 2，如果 CPU 大于 16，则默认上限为 32。

  说明

  OceanBase 数据库 V4.2.1 及之后的版本支持并行导入 DDL。导入 OceanBase 数据库 V4.2.1 之前版本的数据库对象定义时，无需指定该选项。

• --block-size

  用于标识文件块的切分阈值，支持的 LONG 数据类型。例如，--block-size 64 表示单个文件大小不超过 64MB。指定该选项时无需显式标注单位，默认单位为 MB，默认值为 64。默认情况下 OBLOADER 对大文件按照 64MB 自动拆分成多份逻辑子文件，逻辑子文件不会占用额外的存储空间。

• --max-tps int_num

  用于标识最大导入的 TPS。指定该选项时，可保证平稳的导入速率。

• --max-wait-timeout int_num

  用于标识 OceanBase 服务端合并的等待时长。指定该选项时，无需显式标注单位，默认单位：小时。OceanBase 服务端处于合并状态时，客户端进入停导模式，最大等待时长不可超过该选项的值。默认值：3。

其它选项

• --truncate-table

  用于标识导入数据前对目标库中表进行截断操作。该选项仅与任意一种数据格式选项搭配使用，其与 --all 或者 --table '*' 选项搭配使用时，表示截断数据库中所有的表。如果仅需要截断部分表，可以显式指定 --table 'test1,test2,[....]'。该选项与 --with-data-files 选项搭配使用时，表示仅截断有对应数据文件的表。

  注意

  • 导入数据使用 --all 或者 --table '*' 选项搭配 --truncate-table 选项时，程序会截断目标库中所有的表，即使 -f 选项指定的目录下没有表对应的数据文件，程序也会执行 truncate table 操作。
  • 请勿使用该选项对目标库或者目标表进行截断操作，强烈建议用户根据业务需求手动截断表，避免对业务造成影响。

• --with-data-files

  该选项与 --truncate-table 或者 --delete-from-table 选项搭配使用时，表示导入数据前截断或者清空有对应数据文件的表。单独指定该选项无任何意义。

• --delete-from-table

  用于标识导入数据前删除目标库中所有的表中的数据。该选项仅与任意一种数据格式选项搭配使用，其与 --all 或者 --table '*' 选项搭配使用时，表示删除目标库中所有表中的数据。如果仅需要删除部分表中的数据，可以显式指定 --table 'test1,test2,[....]'。该选项与 --with-data-files 选项搭配使用，表示仅删除有对应数据文件的表中的数据。

  注意

  • 导入数据使用 --all 或者 --table '*' 选项搭配 --delete-from-table 选项时，程序会删除目标库中所有表中的数据，即使 -f 选项指定的目录下没有表对应的数据文件，程序也会执行 delete from table 操作。
  • 请勿使用该选项删除目标库或者目标表中的数据，特别是数据量比较大的表。强烈建议用户根据业务需求手动删除表中的数据，避免对业务造成影响。

• --replace-object

  用于标识导入数据库对象定义时替换已存在的数据库对象定义。对于 表 、 同义词 等对象使用先删除再创建的方式进行替换；对于 函数 、 存储过程 等对象使用 CREATE OR REPLACE 进行替换。该选项仅与 --ddl 或者 --mix 选项搭配使用，对 --csv, --sql 等其它数据格式选项不生效。

  注意

  • 目标库中已经存在对象时，该对象会被强制替换成文件中所保存的对象定义。
  • 用户不需要替换数据库中的对象时，请勿使用该选项，避免对业务造成影响。

• --session-config

  用于指定 连接配置 文件。程序包中已为您提供一份默认的配置文件：<工具根目录>/conf/session.config.json，您无需配置即可生效。建议仅当您需要使用同一份程序包加载多份连接配置时指定该选项。

• --external-data

  用于标识导入的数据集是由第三方工具导出的。OBDUMPER 导出数据时，工具会在 -f 指定的目录中生成 MANIFEST.bin 文件用于保存元数据信息。OBLOADER 导入数据时，默认会解析该元数据文件。如果该文件丢失，或者数据是由第三方工具导出而没有元数据文件，导入时可以指定该选项跳过元数据解析。

选项列表