UXDB COPY语句异常处理能力增强，让数据复制更稳健

在数据库迁移与集成的关键任务中，时常面临一个棘手挑战：使用COPY 命令从文件导入数据到表时。由于源数据中偶尔混杂的格式异常，往往导致整个数据导入流程意外中断。这不仅需要人工干预，更可能影响项目进度，导致项目成本攀升。

为此，UXDB 对 COPY FROM 命令进行了重要增强，引入了细粒度的异常处理机制。该功能将控制权交还给用户，通过多种策略从容应对数据异常，显著提升数据迁移流程的自动化和可靠性。

一、精细化的异常处理策略

传统的数据导入工具在面对错误时往往只有“中断”或“全部跳过”两种选择，缺乏灵活性。UXDB copy新增了一组参数，为用户提供了从“严格中断”到“灵活容错并记录”的完整策略：

STOP (报错退出)：默认策略。在遇到首个无法处理的异常时立即终止任务，确保数据的绝对完整性与一致性，适用于对数据质量要求极高的场景。
IGNORE (忽略异常行)：跳过存在问题的数据行，继续处理后续数据。这能保证主体数据的顺利导入，适用于允许极少量数据缺失且后续可补录的场景。
SETNULL (异常列置空)：当单列数据转换失败（如非法日期）时，将该列值置为 NULL，同时成功导入该行其他有效数据。这最大程度地保留了数据记录的完整性，便于事后针对性修复。
STOREFILE (记录至文件)：将异常行的原始数据完整转储到指定的外部文件中。这为数据审计和问题排查提供了清晰的原始依据，方便技术团队离线分析数据根源问题。
STORETABLE (记录至表)：将异常行及其错误信息结构化地保存到指定的数据库表中。这是最先进的处理方式，实现了异常数据的在线化管理，支持通过SQL直接查询、分析和批量处理异常数据，大幅提升了运维效率。

二、强大的辅助控制参数

围绕核心的 ON_ERROR 策略，UXDB 提供系列辅助参数，实现对流程的精准控制：

可控的容错阈值 (REJECT_LIMIT)：允许用户设置一个异常行数的上限。一旦异常数量超过此阈值，任务将自动终止。这有效防止了因源文件大面积错误而导致的“垃圾数据”无意义导入，在灵活性与数据质量间设立了安全边界。
可定制的错误存储 (ON_ERROR_FILE/TABLE)：用户可以自由指定存储异常的文件路径或表名（支持 database.schema.table 格式），管理策略更加灵活。
可调节的日志输出 (LOG_VERBOSITY)：提供 SILENT、DEFAULT、VERBOSE 三级日志详细度，让用户能在安静执行、标准提示和详细调试信息之间灵活切换，适应不同运维阶段的需求。

三、技术实现与价值

该功能在UXDB内核层面实现，确保了处理的高性能和稳定性。其核心是在数据解析和类型转换的关键路径上，增加了异常捕获与分发逻辑。系统会根据用户预设的策略，在行级别和列级别做出实时决策，从而实现精准容错。

为客户带来的核心价值包括：

提升迁移成功率：根本上解决因零星数据错误导致的整个迁移任务失败问题，保障项目主线进度。
降低运维成本：自动化处理异常，避免人工逐条排查、清洗数据的高成本操作，将运维人员从重复劳动中解放出来。
增强流程管控：通过异常行记录（尤其是记录到表的方式），提供了完整的数据质量审计线索，形成“导入-发现-修复”的闭环管理。
保持性能高效：异常处理逻辑仅针对问题数据触发，对海量正常数据的导入性能无影响。

四、测试用例

以下为测试 COPY FROM 异常处理功能的 data.csv 模拟数据文件。数据包含多种典型异常，可用于测试 STOP（报错退出）、IGNORE（忽略）、SETNULL（置空）、STOREFILE（存文件）和 STORETABLE（存表）等不同处理策略。

4.1 数据文件：复制到excel，另存为data.csv

id,name,join_date,salary,is_active
1,Alice Smith,2023-01-15,65000.50,true
2,Bob Johnson,0000-11-31,invalid_salary,false
3,Charlie Brown,2022-08-10,48000.00,maybe
4,"Diana, Prince",not_a_date,72000.80,true
5,Edward "Buddy",1995-03-25,,yes
6,Fiona Green,2018-12-40,55000.00,false
7,George Hill,2020-05-18,61000.75
8,Helen,2021-07-07,83000.20,true,extra_column
9,Ivan,1999-09-09,77000.00,false
10,Jane Doe,2024-02-29,92000.40,true

4.2 数据异常点说明

行号	列名	异常值	异常类型	测试目的
2	`join_date`	`0000-11-31`	无效日期（月份、日不合法）	测试对日期类型异常的容错。
2	`salary`	`invalid_salary`	字符串无法转换为数值	测试数值类型转换失败的处理。
3	`is_active`	`maybe`	字符串无法转换为布尔值	测试布尔类型转换失败的处理。
4	`join_date`	`not_a_date`	非日期字符串	测试日期解析的严格性。
4	`name`	`"Diana, Prince"`	包含引号和分隔符	测试CSV引号转义和解析。
5	`salary`	（空）	空字符串	测试 `FORCE_NULL` 或空值处理。
5	`is_active`	`yes`	非标准布尔值	测试布尔值转换的灵活性。
6	`join_date`	`2018-12-40`	无效日期（日不合法）	测试日期边界检查。
7	整行	缺少最后一列（`is_active`）	列数不足	测试列数不匹配的处理。
8	整行	多出一列（`extra_column`）	列数过多	测试列数不匹配的处理。

4.3 建表SQL与测试命令

创建目标表 (在UXDB中执行):

CREATE TABLE test_employees (
    id INTEGER,
    name TEXT,
    join_date DATE,
    salary NUMERIC(10, 2),
    is_active BOOLEAN
);

创建异常记录表 (用于测试 ON_ERROR 'STORETABLE'):

CREATE TABLE error_log (
    id SERIAL PRIMARY KEY,
    err_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    raw_line TEXT,
    error_message TEXT
);

使用不同异常处理模式进行测试 (在 uxsql 中使用 \copy):
- 模式1：报错退出 (默认)
```
\copy test_employees FROM 'data.csv' WITH (FORMAT csv, HEADER true);
```
  - 预期结果：在遇到第一行异常（第2行）时立即停止，并报错。
- 模式2：忽略异常行并记录到表
```
\copy test_employees FROM 'data.csv' WITH (FORMAT csv, HEADER true, ON_ERROR 'storetable', ON_ERROR_TABLE 'error_log');
```
  - 预期结果：正常行（1, 3, 4, 5, 9, 10）被导入test_employees表；所有异常行（2, 6, 7, 8）的原始数据将被记录到 error_log 表中，便于后续审计。
- 模式3：异常列置空
```
\copy test_employees FROM 'data.csv' WITH (FORMAT csv, HEADER true, ON_ERROR 'setnull');
```
  - 预期结果：所有行都会被尝试导入。对于有异常的列（如Bob的salary、Charlie的is_active），该列会被置为 NULL，但该行其他有效数据会被保留。
- 模式4：设置容错上限
```
\copy test_employees FROM 'data.csv' WITH (FORMAT csv, HEADER true, ON_ERROR 'ignore', REJECT_LIMIT 2);
```
  - 预期结果：当忽略的异常行数累计超过2行时，整个操作会报错终止，防止因源文件大面积错误导致不可控的结果。

4.4 测试建议

每次测试前，可使用 TRUNCATE TABLE test_employees; 清空目标表。
执行后，通过 SELECT * FROM test_employees; 和 SELECT * FROM error_log; 分别查看导入结果和异常记录，验证不同模式的行为是否符合预期。
这个数据集能很好地体现UXDB在数据迁移场景下，针对数据质量不完美的源头所提供的强大控制力和灵活性。

五、结语

稳健的数据传输能力与高效的数据处理能力，对生产场景中海量复杂的数据非常重要。UXDB 增强的 COPY 异常处理机制，正是这一理念的体现。赋予了用户在数据迁移过程中应对不确定性的强大工具，让数据复制流程之路能稳健前行，直达业务价值的彼岸。

软件试用

本功能由我司UXDB社区版(2.1.2.6A)提供试用，欢迎与我们联系：product@uxsino.com，获取最新的试用版本。