错误处理 | OceanBase 文档中心

错误处理

更新时间：2026-06-15 15:40:17

如果导入的数据中存在 Bad Record 或者 Discard Record 类型错误时，用户可以使用 OBLOADER 4.2.4 及之后的版本控制此类脏数据对进程结束状态。用户可以根据生成的报错文件，手动修复此类错误。

本文档旨在介绍使用 OBLOADER 导入数据时处理错误的机制与可选参数。

错误类型

有效错误

数据错误

错误类型	说明
数据类型不匹配	例如：将 VARCHAR 类型数据插入到 INT 类型的列中。
非法的 NULL 值	设置了非空约束。
数据类型溢出	字符串超长或者整型超长。
预处理数据失败	使用控制文件，预处理函数调用失败。
列数不匹配	文件列数与数据库列数不匹配。
主键或者唯一键重复	表中的主键或者唯一键出现重复。

说明

导入数据出现数据错误时，导入任务不可重试。
用户可以在 {ob-loader-dumper}/logs/ob-loader-dumper.bad 文件中查看数据类型不匹配/非法的 NULL 值/数据类型溢出/预处理数据失败/列数不匹配错误；在 {ob-loader-dumper}/logs/ob-loader-dumper.discard 文件中查看主键或者唯一键重复错误。

环境错误

错误类型	说明
网络错误	连接超时。连接断开。 IO 超时。
数据库系统错误	事务终止。事务回滚。租户内存达到阈值。服务端超时。

说明

导入数据出现环境错误时，单个导入任务可重试最多 5 次，不支持自定义重试数量。达到重试阈值后，导入任务会失败并结束进程。
导入包含非主键/非唯一键的表出现环境错误时，导入任务不会重试，且当前子任务标记为失败，以避免同一批数据的二次插入。

无法处理的错误

错误类型	说明
原始文件不可读	例如：文件已损坏；缺少磁盘访问权限等。
原始文件语法错误	例如：CSV 文件缺失定界符；SQL 文件缺少换行符等。
无法连接数据库	例如：客户端与服务端网络不通；连接参数错误等。
操作系统错误	例如：JVM OOM；进程被异常终止。

说明

导入数据出现无法处理的错误时，导入任务不可重试，且导入失败并结束进程。

最佳实践

该示例中，导入的数据存在已知的错误。出现该错误的解决方法如下：

准备数据。

示例语句：

DROP TABLE IF EXISTS `example`;
CREATE TABLE `example` (c1 TINYINT PRIMARY KEY, c2 VARCHAR(12) NOT NULL UNIQUE);

INSERT INTO `example` (c1, c2) VALUES
 (0, NULL),              -- 列不为空
 (1, 'one'),
 (2, 'two'),
 (40, 'forty'),          
 (50, 'fifty-four'),     
 (77, 'seventy-seven'),  -- 字符串长度超过 12 个字符
 (600, 'six hundred'),   -- 数字超出了 TINYINT 数据类型支持的范围
 (40, 'forty'),         -- 与上述 `40` 冲突
 (42, 'fifty-four');     -- 与上述 `'fifty-four'` 冲突

通过 OBLOADER 导入数据，并指定 --strict 选项跳过错误并继续进程。

示例语句：
```
$./obloader -h xx.x.x.x -P 2883 -u test -p ****** --sys-user **u*** --sys-password ****** -c cluster_a -t mysql -D USERA --csv --table 'example'  -f /output --strict
```
其中，--strict 选项的默认值为 true，表示导入数据中存在 Bad Record 或者 Discard Record 类型错误时会以失败状态结束程序（System exit 1）。如果用户期望脏数据不影响程序最终结束状态（System exit 0），需要指定 --strict=false。--strict 选项可与 --max-discards 或者 --max-errors 选项搭配使用，表示当重复数据量或者错误数在指定范围内，会跳过错误继续进程。

运行 OBLOADER，删除错误数据并跳过 4 个错误。

任务结果示例：

...
2023-07-11 06:25:22 [WARN] Bad records were found in file: "/home/admin/obloaderobdumper/output/data/USERA/TABLE/example.1.0.csv". Check "ob-loader-dumper.bad" for details
2023-07-11 06:25:22 [WARN] Skipped 4 problematic records for table `USERA`.`example`. Check "logs" folder for details
2023-07-11 06:25:24 [INFO] Drain and halt the worker group finished
2023-07-11 06:25:24 [INFO] Close connections: 26 of the BIZ DataSource.
2023-07-11 06:25:24 [INFO] Shutdown task context finished
2023-07-11 06:25:24 [ERROR] Error: Skipped 4 problematic records for table `USERA`.`example`. Check "logs" folder for details
2023-07-11 06:25:24 [INFO] ----------   Finished Tasks: 1       Running Tasks: 0        Progress: 100.00%       ----------
2023-07-11 06:25:24 [INFO]

All Load Tasks Finished:

----------------------------------------------------------
|  No.#  | Type   | Name       | Count       | Status    | 
----------------------------------------------------------    
|  1     | TABLE  | example     | 9 -> 5     | FAILURE   |                
----------------------------------------------------------

Total Count: 5          End Time: 2023-07-11 06:25:24

2023-07-11 06:25:24 [INFO] Load record finished. Total Elapsed: 3.281 s
2023-07-11 06:25:24 [ERROR] System exit 1
...

导入的数据示例：

...
SELECT * FROM `example`;
+----+------------+
| c1 | c2         |
+----+------------+
|  0 | NULL       |
|  1 | one        |
|  2 | two        |
| 40 | forty      |
| 50 | fifty-four |
+----+------------+
5 rows in set (0.05 sec)
...

查看错误详情。

说明

在 {ob-loader-dumper}/logs/ob-loader-dumper.bad 文件中查看数据类型不匹配/数据类型溢出错误。
在 {ob-loader-dumper}/logs/ob-loader-dumper.discard 文件中查看主键或者唯一键重复错误。

...
cd /output/logs
cat ob-loader-dumper.bad
INSERT INTO example (`c1`,`c2`) VALUES ('77','seventy-seven');
Cause: Data too long for column 'c2' at row 1   

INSERT INTO example (`c1`,`c2`) VALUES ('600','six hundred');
Cause: Out of range value for column

cat ob-loader-dumper.discard
INSERT INTO example (`c1`,`c2`) VALUES ('40','forty');
INSERT INTO example (`c1`,`c2`) VALUES ('42','fifty-four');
...

根据错误提示手动修复此类错误。