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 行，采样区间之外的分布倾斜要到全量执行才暴露。
三步行动清单
- 打开源文件首行，统计分隔符个数以判定
delimiter与encoding；无 BOM 且中文乱码时改为GBK。 - 在导入向导设置批次行数与冲突策略，对生产数据先建表快照再执行。
- 任务结束后核对行数，用
loadErrors中的异常定位残留行单独补导。
DBeaver 是通用数据库工具，这套工作流覆盖 CSV 等流式数据源；大二进制对象与跨库分布式事务不在该流程的保证范围内。
【免费下载链接】dbeaverFree universal database tool and SQL client项目地址: https://gitcode.com/GitHub_Trending/db/dbeaver
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
、安装和使用方法、案例应用之详细攻略)
