命令行选项

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

选项介绍

选项风格

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

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

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

选项分类

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

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

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

必选选项

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

基础选项

连接选项

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

导出类型

功能选项

文件格式

压缩导出

导数工具 V4.3.0 及之后版本，支持压缩导出 CSV、CUT、POS 和 SQL 等可读文件格式，您可以通过下述命令行选项进行相关配置。

• --compress

  布尔值，用于标识导出时是否进行压缩。

• --compression-algo

  字符串，用于指定压缩格式。可选值包括 zstd、zlib、gzip 和 snappy，默认值为 zstd。

• --compression-level

  整型，用于指定对应压缩格式的压缩等级。各类压缩格式支持的压缩等级如下：

  • zstd 支持 1 ~ 22，默认值为 3。

  • zlib 支持 -1 ~ 9，默认值为 -1。

  • gzip 和 snappy 不支持指定压缩等级。

数据库对象类型

• --all

  用于标识导出所有的数据库对象定义和表数据，是 --trigger、--view 等数据库对象类型的集合，使用限制等事项以具体的数据库对象类型为准。

  • 该选项与 --ddl 搭配使用时，表示导出所有的数据库对象定义。对于 --trigger 等仅适用于 OceanBase Oracle 模式的数据库对象类型，OceanBase MySQL 租户设置 --all --ddl 后，同样无法导出 trigger 的 DDL。

  • 该选项与 --csv, --sql, --cut 任意一种数据格式选项搭配使用时，表示按照对应的格式导出所有表中的数据。如果需要导出所有的数据库对象定义和表数据，您可以指定 --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 表。如果表名指定为星号（*），表示导出所有的表定义或者表数据。

  说明

  OBDUMPER V4.1.0 及之后的版本支持导出 OceanBase Oracle 模式下的临时表定义。

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

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

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

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

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

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

  注意

  OBDUMPER V4.0.0 及之前的版本仅适用于 OceanBase Oracle 模式；OBDUMPER 4.1.0 及之后的版本适用于 OceanBase MySQL 和 OceanBase Oracle 模式。

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

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

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

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

  说明

  仅 OceanBase 数据库 Oracle 租户 V2.2.77 及之后版本支持导出类型定义。

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

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

  说明

  该选项必须与 --type 搭配使用，导出的类型体文件保存在类型文件中。

• --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 选项。

  说明

  OceanBase Oracle 所有版本均支持导出函数定义；OceanBase 数据库 MySQL 租户 V2.2.30 及之后版本支持导出函数定义。

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

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

  说明

  OceanBase 数据库 Oracle 租户所有版本均支持导出存储过程定义；OceanBase 数据库 MySQL 租户 V2.2.30 及之后版本支持导出存储过程定义。

存储路径

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

  用于指定数据文件存放在本地磁盘的绝对路径。

  说明

  OBDUMPER V4.2.7 及之后的版本，导出单个文件时支持指定 -f 为具体的文件名。

  • 指定 --query-sql 时，会替换默认的文件名 CUSTOM_SQL。
  • log 目录会被生成在 -f 指定路径的父目录。

  OBDUMPER 支持将数据库对象定义和表数据导出至本地磁盘、Aliyun OSS、Amazon S3、Tencent COS 和 Huawei OBS。语法格式如下：

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

  组成部分	说明
  scheme	支持的存储类型，包括 Aliyun OSS、Amazon S3、Tencent COS 和 Huawei OBS。 如果指定的 scheme 不是当前支持的 OSS、S3、COS 和 OBS，则会报错。
  host	指定存储空间的名称。 导出数据至 OSS、S3、COS 和 OBS 时，host 指代存储桶，详情请参见 OSS Bucket。
  path	指定存储空间的资源路径。路径必须以 / 开头。
  parameters	指定请求所需要的参数。 parameters 可为单个 key 或者 key-value。

  支持的参数：

  参数	是否需要 value	说明	支持的存储类型	支持版本
  endpoint	是	用于指定 OSS host 所在地域的 Endpoint。 用于通过域名 Endpoint 访问 S3/COS/OBS。	OSS/S3/COS/OBS	OSS：V4.2.0 S3：V4.2.5 COS/OBS：V4.3.0
  region	是	用于指定终端节点，为 bucket 所在的物理位置。	S3/COS/OBS	S3：V4.2.0 COS/OBS：V4.3.0
  storage-class	是	用于指定 Amazon S3 存储类。	S3	4.2.0
  access-key	是	用于指定存储的访问账号。	OSS/S3/COS/OBS	OSS/S3：V4.2.0 COS/OBS：V4.3.0
  secret-key	是	用于指定存储的访问密钥。	OSS/S3/COS/OBS	OSS/S3：V4.2.0 COS/OBS：V4.3.0

  示例如下：

  • 导出数据至本地磁盘

    -f '/home/admin/foo/bar' 
    

  • 导出数据至 S3

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

  • 导出数据至 OSS

    -f 'oss://mybucket/foo/bar?endpoint=myendpoint&access-key=myak&secret-key=mysk' 
    

  • 导出数据至 COS

    -f 'cos://mybucket/foo?region=ap-shanghai&access-key=myak&secret-key=mysk'
    -f 'cos://mybucket/foo?endpoint=yourendpoint&access-key=myak&secret-key=mysk'
    

  • 导出数据至 OBS

    -f 'obs://mybucket/foo?region=cn-north-1&access-key=myak&secret-key=mysk'
    -f 'obs://mybucket/foo?endpoint=yourendpoint&access-key=myak&secret-key=mysk'
    

• --ctl-path 'control_path'

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

• --log-path 'log_path'

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

• --no-nested-dir

  用于导出扁平的目录结构，所有文件都会导出至 -f 指定的目录下，不会生成任何子目录层级。

• 工具使用 Multipart-Upload 方式导出至对象存储，默认使用本地文件系统作为临时目录（也可以使用 --tmp-path 指定），以存放临时文件分块。您可以在 OBDUMPER 运行脚本中修改以下参数来适应实际的导数环境。

  • upload.buffer.type

    用于指定 buffer 类型，可选值包括 disk 和 bytebuffer。其中 disk 为默认值，使用磁盘来存储分块，将受到磁盘的最大可用空间限制。bytebuffer 使用内存来存储分块，性能较好但是会占用大量 JVM 堆内存。

  • upload.buffer.size

    用于指定每个分块的大小，以字节数表示，默认值为 64 MB。

  • upload.active.blocks

    用于指定每个写线程最多可以同时存在的分块（可能在上传中，也可能在队列中等待上传），默认值为 2。当超过该值时，程序会阻塞，直到某一个分块上传完成被移出等待队列。

    由于 --thread 会限制写线程的最大数量，您可以通过公式 thread * active.blocks * buffer.size 来估算程序运行时 buffer 可能会占用的空间。

其它选项

• -H, --help

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

• -V, --version

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

高级选项

功能选项

时间戳格式

• --flashback-timestamp 'timestamp_string'

  用于导出闪回时间点之后的数据。该选项仅与任意一种数据格式选项搭配使用，不可与 --query-sql 选项搭配使用。仅适用于 OceanBase Oracle 模式。

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

  用于设置 OceanBase Oracle 模式下的 nls_date_format 会话变量，其不代表将 DATE 类型的数据按照该选项指定的格式导出。默认值：YYYY-MM-DD HH24:MI:SS。

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

  用于设置 OceanBase Oracle 模式下的 nls_timestamp_format 会话变量，其不代表将 TIMESTAMP 类型的数据按照该选项指定的格式导出。默认值：YYYY-MM-DD HH24:MI:SS:FF9。

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

  用于设置 OceanBase Oracle 模式下的 nls_timestamp_tz_format 会话变量，其不代表将 TIMESTAMP WITH TIME ZONE 类型的数据按照该选项指定的格式导出。默认值：YYYY-MM-DD HH24:MI:SS:FF9 TZR。

• --date-value-format

  用于设置 DATE 类型的导出格式。OceanBase MySQL 模式下，DATE 类型的默认格式：yyyy-MM-dd，OceanBase Oracle 模式下的默认格式：yyyy-MM-dd HH:mm:ss。

  说明

  • 该选项仅与 --csv 或者 --cut 选项搭配使用。
  • OceanBase MySQL 模式下，DATE 为零值时，该选项不支持设置 DATE 类型的格式。

• --time-value-format

  用于设置 TIME 类型的导出格式。OceanBase MySQL 模式下，TIME 类型的默认格式：HH:mm:ss，精度值与表定义中的精度值一致。

  说明

  • 该选项仅与 --csv 或者 --cut 选项搭配使用。
  • OceanBase MySQL 模式下，TIME 为零值时，该选项不支持设置 TIME 类型的格式。

• --datetime-value-format

  用于设置 DATETIME 类型的导出格式。OceanBase MySQL 模式下，DATETIME 类型的默认格式：yyyy-MM-dd HH:mm:ss，精度值与表定义中的精度值一致。

  说明

  • 该选项仅与 --csv 或者 --cut 选项搭配使用。
  • OceanBase MySQL 模式下，DATETIME 为零值时，该选项不支持设置 DATETIME 类型的格式。

• --timestamp-value-format

  用于设置 TIMESTAMP 类型的导出格式。 OceanBase MySQL/Oracle 模式下，TIMESTAMP 类型的默认格式：yyyy-MM-dd HH:mm:ss.SSSSSS，精度值与表定义中的精度值一致。

  说明

  • 该选项仅与 --csv 或者 --cut 选项搭配使用。
  • OceanBase MySQL 模式下，TIMESTAMP 为零值时，该选项不支持设置 TIMESTAMP 类型的格式。

• --timestamp-tz-value-format

  用于设置 TIMESTAMP WITH TIME ZONE 类型的导出格式。OceanBase Oracle 模式下，TIMESTAMP WITH TIME ZONE 类型的默认格式：yyyy-MM-dd HH:mm:ss.SSSSSS，精度值与表定义中的精度值一致。

  说明

  该选项仅与 --csv 或者 --cut 选项搭配使用。

• --timestamp-ltz-value-format

  用于设置 TIMESTAMP WITH LOCAL TIME ZONE 类型的导出格式。OceanBase Oracle 模式下，TIMESTAMP WITH LOCAL TIME ZONE 类型的默认格式：yyyy-MM-dd HH:mm:ss，精度值与表定义中的精度值一致。

  说明

  该选项仅与 --csv 或者 --cut 选项搭配使用。

• --preserve-zero-datetime

  用于在导出时保留日期与时间类型零值的原始格式。指定该选项时，会将非空约束下的日期与时间类型列值 NULL 导出为 0；可空列值 NULL 仍导出为 NULL。 该选项支持设置 MySQL 模式下的 DATE, DATETIME, TIMESTAMP 类型。

黑白名单筛选

• 表黑白名单筛选

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

    用于表示导出表定义或者表数据时排除指定的表。表名支持模糊匹配。

    使用示例：--exclude-table 'test1,test*,*test,te*st'

    上述参数表示导出表定义或者表数据时排除的表包括：

    • test1

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

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

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

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

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

  • --add-extra-message

    用于标识导出表定义中包含的额外信息。例如：命令行指定 --add-extra-message 选项导出表定义时，程序会导出每张表所属的表组名。默认 OBDUMPER 不会导出表定义中包含的额外信息。

    注意

    指定 --add-extra-message 命令行选项导出表定义时，程序会导出每张表所属的表组名。该选项依赖 sys 租户权限。如果 OBDUMPER 运行时缺少 sys 租户的权限，请勿指定该选项。

  • --retain-empty-files

    用于表示特定场景进行导出时生成空文件。命令行在指定 --partition 选项进行特定分区导出，或指定了 --where 进行条件查询导出时，同时指定 --retain-empty-file 可以在分区为空或条件查询结果集为空时生成空文件。

• 列黑白名单筛选

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

    用于根据指定的列名导出数据。

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

    用于表示导出数据时排除指定的列。列名不支持模糊匹配。

    注意

    指定的列名需要与表定义中的列名大小写保持一致。

  • --where 'where_condition_string'

    用于标识导出满足指定条件的数据。该选项仅与任意一种数据格式选项搭配使用，不可搭配 --query-sql 选项使用。

    如果您在指定了 --where 进行条件查询导出时，同时指定 --retain-empty-file，则可以在条件查询结果集为空时生成空文件。

  • --partition 'partition_name [, partition_name...]'

    用于标识导出指定分区的数据。该选项的参数值是分区名，多个分区名用逗号分隔。该选项仅与任意一种数据格式选项搭配使用，不可搭配 --query-sql 选项使用。

    注意

    • 指定分区导出时，对于二级分区表需要指定二级分区名，无法按照一级分区名导出。如果是模版二级分区，对应的分区名为：一级分区名+s+二级分区名。
    • 命令行指定 --partition 选项导出分区内的数据时，对于组合分区表需要指定二级分区名，OBDUMPER 无法导出一级分区内的数据。如果指定的分区名不存在，OBDUMPER 会报错提示。
    • 如果您在指定 --partition 选项进行特定分区导出时，同时指定 --retain-empty-file，则可以在分区为空时生成空文件。

  • --query-sql

    • 直接指定查询语句 --query-sql '<select_statement>'。例如，--query-sql 'select c1,c2 from test where c1 is not null'。

      用于标识导出自定义查询语句的结果数据。该选项不与 --partition, --where 选项搭配使用。用户需要保证自定义查询语句的正确性和查询性能。如果导出大查询语句的结果集，可能等待数据库的响应时间比较长。如果导出数据时需要利用控制文件进行数据预处理，则需要使用 --table 选项和 --ctl-path 选项，并且 --table 选项指定的表名需要与 --ctl-path 选项指定的文件名保持大小写一致。如果不需要进行预处理操作，则 --table 选项可指定为任意的表名。

    • 指定查询语句所存放的文件 --query-sql 'file://xxxx'。例如，--query-sql 'file:///home/admin/t1.sql'。

      导数工具识别 file:// 协议头，直接从文件中读取查询 SQL 语句。用于支持单条超长 SQL 语句，不支持在一个文件中写多条 SQL 语句。

  • --exclude-virtual-columns

    用于标识不导出生成列的数据（默认导出生成列数据）。

  • --enable-hidden-pk

    用于无主键的表使用隐藏主键 __pk_increment，以提升导出速度。OceanBase 4.0.0 之前的版本指定该选项时需要使用特殊用户进行导出。示例：

    # OceanBase MySQL 模式下，使用 root 用户创建一个特殊用户并授权
    create user '__oceanbase_inner_drc_user'@'%' IDENTIFIED BY 'u*******';
    grant ALL on *.* to '__oceanbase_inner_drc_user' WITH GRANT OPTION;
    
    # OceanBase Oracle 模式下，使用 SYS 用户创建一个特殊用户并授权
    create user '__OCEANBASE_INNER_DRC_USER'@'%' IDENTIFIED BY u*******;
    grant ALL to '__OCEANBASE_INNER_DRC_USER';
    

    注意

    使用 OceanBase 数据库 V3.x 的分区表时，建议设置 LOCAL 索引。语法格式：create index "your index" on `your table` ("__pk_increment") local;

  • --fetch-size 'int_num'

    用于标识 OceanBase Oracle 模式下从数据库游标中读取的行数。默认值：1000。具体配置请参考 OceanBase FetchSize。

    说明

    此选项需要安装 OceanBase JDBC 驱动程序。

错误处理

• --retry

  用于从上一次导出失败位置继续导出任务。

  注意

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

• --weak-read

  用于标识从备副本导出数据。关于弱一致性读的更多信息，请参见 弱一致性读。

• --max-file-size int_num

  用于设置进程可以导出的数据量上限。导出的数据超过该选项值时停止导出。

• --skip-check-dir

  用于标识跳过检查导出的数据目录是否为空。导出目录非空时，程序停止导出。

  说明

  • 不指定该选项时，OBDUMPER 会检查目录是否为空，如果导出目录非空，OBDUMPER 会报错并退出。
  • 指定该选项时，OBDUMPER 会跳过检查目录是否为空，但是导出的文件可能会覆盖目录中同名文件的数据。

• --remove-newline

  用于标识导出数据时程序会强制删除数据中的回车符或者换行符。例如： ***\r***, ***\n***, ***\r\n***。其只会对读取到内存中的数据进行修改，并不会直接修改源表中的数据。该选项仅与 --cut 选项搭配使用。

  注意

  源表中的数据包含回车符或者换行符时，指定该选项导出的数据和源表中的数据是不一致的。使用前请确认删除 \r, \n, \r\n 字符不会对业务造成影响。用户不需要删除数据中的回车符或者换行符时，请勿在命令行中指定该选项，避免造成业务数据不一致的问题。

• --snapshot

  用于标识导出历史版本数据。该选项仅与任意一种数据格式选项搭配使用。导出历史版本数据旨在保证导出数据的全局一致性。如果命令行未指定该选项，则导出内存中的实时数据可能不是全局一致的数据快照。

性能选项

• --page-size int_num

  OBDUMPER V4.0.0 之后的版本用于指定任务分页的大小，即每次查询限定多少行记录，默认值为 1000000。例如，每次查询 100 万行。

• --thread int_num

  用于标识并发线程数。该选项直接对应导出线程数。默认值为 CPU 乘以 2，如果 CPU 大于 16，则默认上限为 32。导出多个数据库对象定义时，建议 --thread 选项的参数值不要超过 4。并发数太大会影响工具访问 sys 租户下的系统表，导出时会出现超时错误。

• --block-size

  用于标识文件块的切分阈值，支持 LONG 和 STRING 数据类型。如果导出的数据文件超过该阈值，则依次生成其它逻辑子文件。指定该选项时无需显式标注单位，默认单位为 MB，默认值为 1024MB。该选项对于 ORC 和 Parquet 格式不生效。 OBDUMPER V4.1.0 及之后的版本支持根据行数进行切分。--block-size 的值为数字单位，MB 为存储大小，ROW 为行数大小。例如，--block-size 256ROW 表示单个文件大小不超过 256 行；--block-size 1024 或 --block-size 1024MB 表示单个文件大小不超过 1024MB，不支持 1024M、1GB 等格式。

  注意

  使用 --block-size 时，-f 必须指定为 路径地址。

• --parallel-macro int_num

  用于标识一个线程可以处理的宏块数。默认值：8。

其它选项

• --session-config

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

选项列表