快速入门 - 导数工具 V4.3.3.1 | OceanBase 文档中心

本文档旨在指导用户如何快速使用导数工具。

步骤 1：下载软件

说明

导数工具 V4.2.1 及之后的版本不再区分企业版和社区版。用户可以从社区下载中心获取软件包。

下载最新版本的导数工具软件包并解压：

unzip ob-loader-dumper-4.2.x-RELEASE.zip
cd ob-loader-dumper-4.2.x-RELEASE

步骤 2：配置运行环境

注意

用户的本地环境中必须安装 Java 8+ 并配置 JAVA_HOME 环境变量。强烈建议安装 JDK 1.8.0_3xx 及之后的版本。环境配置详情请参考准备环境。

JVM 内存太小可能会影响导入导出的性能，甚至影响导入导出功能的稳定性。您可以通过 --mem 参数指定 JVM 内存的大小。例如，--mem 4G。

步骤 3：准备数据

使用 OBLOADER 导入功能时，用户可以使用已有的数据文件，或者使用 TPC-H 工具临时生成数据文件。导入的文件内容格式需要符合规范，请参考《准备好您的数据了吗？》识别文件中的数据格式。

步骤 4：创建数据库

使用 OCP 管控平台或者 OBD 命令行工具搭建 OceanBase 集群。
创建测试数据库。
创建测试表并插入数据。（导入时可选）

步骤 5：查看配置文件

导数工具配置文件包括连接配置文件（session.config.json）和运行日志文件（log4j2.xml）。

连接配置文件

连接配置文件（{ob-loader-dumper}/conf/session.config.json）用于配置数据库连接参数。连接数据库时，导数工具会通过连接配置文件中的 JDBC 参数构建 JDBC URL，并在新建的连接下按顺序执行初始化 SQL 语句。您可以在连接配置文件中修改 JDBC 参数和初始化 SQL 语句。连接配置的默认值适用于大多数场景，但在某些特殊情况下，您可能需要手动修改此类参数以适应不同的 OBServer 版本和 ETL 场景。连接配置文件详情请参见连接配置。

日志配置文件

日志配置文件（{ob-loader-dumper}/conf/log4j2.xml）用于查看日志输出路径/日志格式，以及问题自查时调整日志级别。具体配置方法请参见如何自定义导出作业日志文件名。

步骤 6：导入数据

./obloader -h 'IP地址' -P'端口' -u'用户'@'租户'#'集群' -p'密码' -D'库名' --table '表名' --csv -f '文件路径' --sys-password '系统租户密码' --external

说明

本示例仅导入数据不包含模式。更多详情请参见 OBLOADER 命令行选项。

下表为示例中使用的数据库信息：

数据库信息	示例值
集群名	cluster_a
OceanBase DataBase Proxy (ODP) 主机地址	xx.x.x.x
OceanBase DataBase Proxy (ODP) 端口号	2883
集群的租户名	mysql
sys 租户下 root/proxyro 用户名	u*
sys 租户下 root/proxyro 用户的密码	******
业务租户下的用户账号（要求读写权限）	test
业务租户下的用户密码	******
Schema 名称	USERA

导入 DDL 定义文件

场景描述：将 /output 目录下所有已支持的数据库对象定义导入到 Schema USERA 中（OceanBase 数据库 V4.0.0 之前的版本要求提供 sys 租户的密码）。

示例语句：

$./obloader -h xx.x.x.x -P 2883 -u test@mysql#cluster_a -p ****** --sys-user **u*** --sys-password ****** -D USERA --ddl --all -f /output

任务结果示例：

...
All Load Tasks Finished:

---------------------------------------------------------
|  No.#  | Type   | Name       | Count       | Status   | 
---------------------------------------------------------     
|  1     | TABLE  | table      | 1 -> 1      | SUCCESS  |                
---------------------------------------------------------

Total Count: 1          End Time: 2023-05-11 16:02:08
...

说明

--sys-user 选项用于连接 sys 租户下具备特定权限的用户。导入时如果未指定 --sys-user 选项时，默认指定的是 --sys-user root。OceanBase 数据库 V4.0.0 及之后的版本无需指定该选项，详情请参见 OBLOADER 命令行选项。

导入 CSV 数据文件

场景描述：将 /output 目录下所有已支持的 CSV 数据文件导入到 Schema USERA 中（OceanBase 数据库 V4.0.0 之前的版本要求提供 sys 租户的密码）。CSV 数据文件（后缀名 .csv）请参见 RFC 4180 规范，CSV 数据文件以纯文本形式存储，可通过文本编辑器或者 Excel 等工具直接打开。

示例语句：

$./obloader -h xx.x.x.x -P 2883 -u test@mysql#cluster_a -p ****** --sys-user **u*** --sys-password ****** -D USERA --csv --table '*' -f /output

任务结果示例：

...
All Load Tasks Finished:

---------------------------------------------------------
|  No.#  | Type   | Name       | Count       | Status   | 
---------------------------------------------------------     
|  1     | TABLE  | table      | 1 -> 1      | SUCCESS  |                
---------------------------------------------------------

Total Count: 1          End Time: 2023-05-11 16:02:08
...

导入 SQL 数据文件

场景描述：将 /output 目录下所有已支持的 SQL 数据文件导入到 Schema USERA 中（OceanBase 数据库 V4.0.0 之前的版本要求提供 sys 租户的密码）。SQL 数据文件（后缀名 .sql）存储的是 Insert SQL 语句，可通过文本编辑器或者 SQL 编辑器等工具直接打开。

示例语句：

$./obloader -h xx.x.x.x -P 2883 -u test@mysql#cluster_a -p ****** --sys-user **u*** --sys-password ****** -D USERA --sql --table '*' -f /output

任务结果示例：

...
All Load Tasks Finished:

---------------------------------------------------------
|  No.#  | Type   | Name       | Count       | Status   | 
---------------------------------------------------------     
|  1     | TABLE  | table      | 1 -> 1      | SUCCESS  |                
---------------------------------------------------------

Total Count: 1          End Time: 2023-05-11 16:02:08
...

导入 POS 数据文件

场景描述：将 /output 目录下所有已支持的 POS 数据文件导入到 Schema USERA 中（OceanBase 数据库 V4.0.0 之前的版本要求提供 sys 租户的密码）。导入时需要指定控制文件所在的路径。POS 数据文件（默认后缀名 .dat）中的数据是按照固定长度的字节偏移位置所组织的数据，导入时需使用控制文件定义每个字段的固定长度，可通过文本编辑器等工具直接打开。

示例语句：

$./obloader -h xx.x.x.x -P 2883 -u test@mysql#cluster_a -p ****** --sys-user **u*** --sys-password ****** 
-D USERA --table '*' -f /output --pos --ctl-path /output

说明

要求数据库中定义的表名与其对应的控制文件名大小写一致，否则 OBLOADER 无法识别控制文件。控制文件的定义规则请参见预处理函数。

导入 CUT 数据文件

场景描述：将 /output 目录下所有已支持的 CUT 数据文件导入到 Schema USERA（OceanBase 数据库 V4.0.0 之前的版本要求提供 sys 租户的密码）。导入时需要指定控制文件所在的路径，同时使用 |@| 作为列分隔字符串。CUT 数据文件（后缀名 .dat）中的数据是以单个字符或者字符串分隔的数据文件，可通过文本编辑器等工具打开。

示例语句：

$./obloader -h127.1 -P2881 -u test@mysql#cluster_a -p ****** --sys-user **u*** --sys-password ****** -D USERA --table '*' -f /output --cut --column-splitter '|@|' --ctl-path /output

任务结果示例：

...
All Load Tasks Finished:

---------------------------------------------------------
|  No.#  | Type   | Name       | Count       | Status   | 
---------------------------------------------------------     
|  1     | TABLE  | table      | 1 -> 1      | SUCCESS  |                
---------------------------------------------------------

Total Count: 1          End Time: 2023-05-11 16:02:08
...

说明

要求数据库中定义的表名与其对应的控制文件名大小写一致，否则 OBLOADER 无法识别控制文件。控制文件的定义规则请参见预处理函数。

从 Amazon S3 导入数据文件到 OceanBase 数据库

场景描述：将 Amazon S3 云存储空间中的所有已支持的 CSV 数据文件导入到 Schema USERA 中（OceanBase 数据库 V4.0.0 之前的版本要求提供 sys 租户的密码）。

示例语句：

$./obloader -h xx.x.x.x -P 2883 -u test@mysql#cluster_a -p ****** --sys-user **u*** --sys-password ****** -D USERA --csv --table '*' -f 's3://obloaderdumper/obdumper?region=cn-north-1&access-key=******&secret-key=******'

-f 's3://obloaderdumper/obdumper?region=cn-north-1&access-key=******&secret-key=******' 选项为存储路径，其组成部分包括：

组成部分	说明
`s3`	S3 云存储类型。
`obloaderdumper`	S3 存储空间的名称。
`/obdumper`	S3 存储空间的资源路径。
`region=cn-north-1&access-key=****&secret-key=****`	指定请求所需的参数。 `region=cn-north-1`：S3 bucket 所在的物理位置。 `access-key=****`：S3 的访问账号。 `secret-key=****`：S3 的访问密钥。

任务结果示例：

...
All Load Tasks Finished:

---------------------------------------------------------
|  No.#  | Type   | Name       | Count       | Status   | 
---------------------------------------------------------     
|  1     | TABLE  | table      | 3 -> 3      | SUCCESS  |                
---------------------------------------------------------

Total Count: 3          End Time: 2023-05-11 16:02:08
...

从 Aliyun OSS 导入数据文件到 OceanBase 数据库

场景描述：将 Aliyun OSS 云存储空间中的所有已支持的 CSV 数据文件导入到 Schema USERA 中（OceanBase 数据库 V4.0.0 之前的版本要求提供 sys 租户的密码）。

示例语句：

$./obloader -h xx.x.x.x -P 2883 -u test@mysql#cluster_a -p ****** --sys-user **u*** --sys-password ****** -D USERA --csv --table '*' -f 'oss://antsys-oceanbasebackup/backup_obloader_obdumper/obdumper?endpoint=https://cn-hangzhou-alipay-b.oss-cdn.aliyun-inc.com&access-key=******&secret-key=******'

-f 'oss://antsys-oceanbasebackup/backup_obloader_obdumper/obdumper?endpoint=https://cn-hangzhou-alipay-b.oss-cdn.aliyun-inc.com&access-key=******&secret-key=******' 选项为存储的统一资源定位符，其组成部分包括：

组成部分	说明
`oss`	OSS 云存储类型。
`antsys-oceanbasebackup`	OSS 存储空间的名称。
`/backup_obloader_obdumper/obdumper`	OSS 存储空间的资源路径。
`endpoint=https://cn-hangzhou-alipay-b.oss-cdn.aliyun-inc.com&access-key=****&secret-key=****`	指定请求所需的参数。 `endpoint=https://cn-hangzhou-alipay-b.oss-cdn.aliyun-inc.com`：OSS host 所在地域的 Endpoint。 `access-key=****`：OSS 的访问账号。 `secret-key=****`：OSS 的访问密钥。

任务结果示例：

...
All Load Tasks Finished:

---------------------------------------------------------
|  No.#  | Type   | Name       | Count       | Status   | 
---------------------------------------------------------     
|  1     | TABLE  | table      | 3 -> 3      | SUCCESS  |                
---------------------------------------------------------

Total Count: 3          End Time: 2023-05-11 16:02:08
...

从 Apache Hadoop 导入数据文件到 OceanBase 数据库

场景描述：将 Apache Hadoop 云存储空间中的所有已支持的 CSV 数据文件导入到 Schema USERA 中（OceanBase 数据库 V4.0.0 之前的版本要求提供 sys 租户的密码）。

示例语句：

$./obloader -h xx.x.x.x -P 2883 -u test@mysql#cluster_a -p ****** --sys-user **u*** --sys-password ****** -D USERA --csv --table '*' -f 'hdfs://***.*.*.*:9000/chang/parquet?hdfs-site-file=/data/0/zeyang/hdfs-site.xml&core-site-file=/data/0/zeyang/core-site.xml'

-f 'hdfs://***.*.*.*:9000/chang/parquet?hdfs-site-file=/data/0/zeyang/hdfs-site.xml&core-site-file=/data/0/zeyang/core-site.xml' 选项为存储的统一资源定位符，其组成部分包括：

组成部分	说明
`hdfs`	Hadoop 云存储类型。
`**...:9000`	Hadoop 存储空间的名称。
`/chang/parquet`	Hadoop 存储空间的资源路径。
`hdfs-site-file=/data/0/zeyang/hdfs-site.xml&core-site-file=/data/0/zeyang/core-site.xml`	指定请求所需的参数。 `hdfs-site-file=/data/0/zeyang/hdfs-site.xml`：Hadoop hdfsSiteFile 配置文件，其中包含 Apache Hadoop 的配置信息。 `core-site-file=/data/0/zeyang/core-site.xml`：Hadoop hdfsSiteFile 配置文件，其中包含 Hadoop 集群中的核心配置信息。

任务结果示例：

...
All Load Tasks Finished:

---------------------------------------------------------
|  No.#  | Type   | Name       | Count       | Status   | 
---------------------------------------------------------     
|  1     | TABLE  | table      | 3 -> 3      | SUCCESS  |                
---------------------------------------------------------

Total Count: 3          End Time: 2023-05-11 16:02:08
...

云数据库 OceanBase 导入模式和数据

场景描述：用户无法提供 sys 租户密码时，将 /output 目录下所有已支持的数据库对象和数据导入到云数据库 OceanBase Schema USERA 中。

示例语句：

$./obloader -h xx.x.x.x -P 2883 -u test -p ****** -D USERA --ddl --csv --public-cloud --all -f /output

OceanBase 数据库导入模式和数据

场景描述：用户无法提供 sys 租户密码时，将 /output 目录下所有已支持的数据库对象和数据导入到 OceanBase 数据库 Schema USERA 中。

示例语句：

$./obloader -h xx.x.x.x -P 2883 -u test@mysql#cluster_a -p ****** -D USERA --ddl --csv --no-sys --all -f /output

步骤 7：恭喜

您已成功完成导数工具的快速使用！！！

如需了解更多信息，请参考以下步骤进行学习：

阅读产品简介，了解导数工具的原理，主要功能，及与其他工具的差异。想要更详细地理解导数工具，请参考官方文档《OceanBase 导数工具》。
欢迎加入 OceanBase 社区，我们一起和 OceanBase 的研发人员在线上讨论导入导出的问题、需求，以及对于未来的规划。