DBeaver 数据导入完整工作流：从格式判定到一致性校验-开发者社区

DBeaver 数据导入完整工作流：从格式判定到一致性校验

【免费下载链接】dbeaverFree universal database tool and SQL client项目地址: https://gitcode.com/GitHub_Trending/db/dbeaver

DBeaver 数据导入失败，最常见的根源不是数据本身，而是 CSV 格式判定阶段对分隔符、引号与编码的误判。任何一行字段数对不上，后续所有环节都会连锁出错。DBeaver 的导入功能核心位于 org.jkiss.dbeaver.data.transfer 模块：DataTransferState在导入初始化时创建实例并挂载loadErrors列表，任务执行由DTTaskHandlerTransfer驱动，整体流程可拆为三个阶段：导入前配置决策、导入中批量执行与监控、导入后校验与回滚。

导入前·配置决策 ⚠️

分隔符、引号与编码的联合判定

判断依据：源文件首行中候选分隔符的个数等于（目标列数 - 1），且逐行解析后字段数稳定。
操作路径：在源数据配置步骤设置delimiter、quoteChar、encoding三个属性，实现见 DataImporterCSV.java。编码默认 UTF-8，文件经BOMInputStream先行探测 BOM；无 BOM 且中文乱码时，手动将encoding改为GBK。
错误代价：分隔符误判会把一个字段拆成多个，后续列类型采样与逐行解析在每一行都会失败。

标题行与空值的语义配置

判断依据：首行内容与目标表列名一致。
操作路径：将header设为top使首行作为列名；在nullString中填写代表空值的字面量（如N/A），并开启emptyStringNull将空串转为 NULL。
错误代价：未配置时，"N/A" 与空串会作为字面量入库；NULL 落入 NOT NULL 列时，整批在数据库层被拒绝。

列类型采样与手动覆盖

判断依据：预览推断的目标列类型与目标列定义不符，例如数值列被推断为字符串。
操作路径：导入器以columnSamplesCount（默认 100）采样行数推断列类型，在列映射步骤手动修改目标列类型；固定值字段使用DataTransferTransformerConstant与DataTransferTransformerExpression提供的转换规则。
错误代价：类型推断错误会在首批插入时抛出转换异常，整批事务回滚，进度清零。

导入中·执行与监控 💡

批量大小与事务粒度

判断依据：单批内存占用与可接受的失败损失上限。
操作路径：在导入设置中调整批次行数。DatabaseTransferConsumer.java 按批提交事务，批内失败回滚整批。批次过大时内存压力上升，单条坏行会拖垮整批。
错误代价：批次过小提交频率高、吞吐下降；过大则单行失败导致回滚范围扩大。

主键冲突处理策略

判断依据：源数据主键值与目标表已有数据重叠。
操作路径：在冲突选项中选策略。启用"跳过重复行"（ignoreDuplicateRowsErrors）后，实现改为无批量的逐行处理（见DatabaseTransferConsumer第 415 行注释），吞吐低于"预检 + 批量"。
错误代价：不选策略时，导入在首个冲突行中断，必须整轮重跑；盲目跳过则会静默丢失更新数据。

实时错误状态观察

判断依据：进度区错误计数大于 0。
操作路径：执行期间DataTransferState持续将异常汇入loadErrors，hasErrors()是任务判定失败的依据。不要等任务结束，运行中周期性查看错误计数。
错误代价：错误计数持续上升而放任不管，任务结束后文件已消费完毕，只能从头定位。

导入后·校验与回滚 ✅

行数与抽样一致性验证

判断依据：任务成功指示不等于数据正确。
操作路径：对比目标表行数与源文件有效行数；对自增主键表抽样核对首尾区间；用COUNT聚合核对关键列的 NULL 分布。
错误代价：跳过验证，行数偏差会在下游业务读取时暴露，且无从区分是导入丢失还是源文件问题。

异常行定位与残留补导

判断依据：hasErrors()为真，或行数对不上。
操作路径：DataTransferState.java 中loadErrors列表保存了全部异常对象，回到源文件对应行修复后，仅补导该批残留行。
错误代价：整文件重导会制造大量主键冲突，再次落入冲突策略选择的问题。

回退路径的选择

判断依据：失败发生在提交前还是提交后。
操作路径：未提交的数据由DatabaseTransferConsumer在失败时自动回滚，无需处理；已提交但数据有误的场景，回退路径只有 DELETE 或导入前快照，是否在配置阶段建快照需要提前决定。
错误代价：未预设快照时，生产表被错误覆盖后没有可靠恢复手段。

反直觉认知

编码不要默认选 UTF-8：BOMInputStream只在 BOM 存在时起作用，Windows 无 BOM 保存的文件默认是系统 GBK 编码，必须手动指定。
开启"跳过重复行"不是免费的优化：源码注释明确该选项伴随逐行无批量处理，吞吐低于"预检 + 批量"路线。
预览通过不等于全量通过：列类型推断只基于columnSamplesCount采样的 100 行，采样区间之外的分布倾斜要到全量执行才暴露。