DBeaver 数据导入实战：3 个阶段把 CSV 批量导入失败率压到最低
【免费下载链接】dbeaverFree universal database tool and SQL client项目地址: https://gitcode.com/GitHub_Trending/db/dbeaver
按本文的导入前、导入中、导入后三个阶段逐步操作，你可以在 DBeaver 中把 CSV 数据迁移到目标数据库时的大部分常见故障（编码乱码、类型不匹配、主键冲突）提前拦截，或快速定位到出错的具体行。整个流程不需要改一行代码，普通用户照着做即可。
导入前：先做 3 项检查再点"开始"
DBeaver 的 CSV 导入由数据传输模块驱动，它默认按 UTF-8 编码、逗号分隔、首行为表头来解析文件。如果你的源文件不符合这些假设，问题会在导入中途才暴露，修复成本很高。因此先在导入向导的设置页核对三项内容：
| 检查项 | 如何确认 | 不通过时怎么办 |
|---|---|---|
| 文件编码 | 用文本编辑器以 UTF-8 打开文件，中文、重音字符是否正常显示 | 在导入设置的编码选项里手动指定 GBK、Latin-1 等实际编码 |
| 分隔符与引号 | 查看首行数据：字段数是否与表头列数一致；分号制表符文件要单独指定 | 在设置中改分隔符，并确认引号字符（单引号/双引号）与文件一致 |
| 表头行 | 首行是列名还是第一条数据 | 选择"首行为表头"或"无表头"，后者时按顺序给列命名 |
为什么这些选项重要：CSV 解析逻辑集中在 DataImporterCSV.java 中，它按上述编码、分隔符、引号参数逐行切分字段——读一遍这个文件就能回答"我的文件为什么被解析成了错误列数"这类问题。
确认三项都通过后，再执行预览：导入向导会渲染前若干行，此时重点看两点——每行列数是否一致（列数漂移通常意味着引号未配对）、数值和日期列是否看起来是规整的值。预览这一步是整个流程性价比最高的检查，建议固定为习惯。
导入中：列映射和主键策略是成败关键
列映射与类型转换
进入映射页后，DBeaver 会按源列名与目标表列名做自动匹配，并给出每列的类型推断。逐项确认：
- 名字相同但含义不同的列（如
id与id指向不同实体）要手动改绑或置空； - 源列带千位分隔符的数值（如
123,456.78）目标列为数字时，先做数据转换或预处理去掉分隔符，否则整行会报类型错误； - 日期列如果格式不统一（混有
MM/dd/yyyy和YYYY-MM-DD），先统一为 ISO 格式再导入，因为格式错配不会报错，只会写入错误日期。
映射确认后，目标列类型以映射页显示为准，不要相信源文件的列名。
主键冲突选哪种策略
目标表已有数据时，重复主键是最高频的失败原因。DBeaver 在目标表设置中提供三种加载策略，按场景选择：
| 场景 | 推荐策略 | 理由 |
|---|---|---|
| 全量初始化空表，中途想续传 | 忽略冲突（跳过重复行） | 不破坏已有数据，重复行自动跳过，可安全重跑 |
| 同步更新，以新数据为准 | 先删后插（删除旧行再插入） | 保证结果与源数据完全一致，包括被删除的行 |
| 仅更新已有记录的新值 | 更新现有 | 保留旧数据中新增列的值，适合增量修正 |
⚠️ 注意：批量插入模式下，部分数据库在"忽略冲突"时可能整批回退，DBeaver 会在出错时逐行重试。如果你发现某一批反复失败，把批量大小调小可以缩小影响范围。
批量大小与事务控制
对十万行以上的大文件，参数建议：
- 每批行数从 1000 起步；出现批量错误或内存压力就减半，直到 100；
- 提交策略选"每批提交"，避免长事务占用连接；
- 如果目标库对单条 SQL 长度敏感，优先降批量而不是关事务。
这些参数对应的是 DTTaskHandlerTransfer.java 里的任务执行逻辑——读它能弄清"一批失败时是整批回滚还是部分入库"，从而判断重跑前是否需要清理脏数据。
导入后：三步完成验证与修复
第 1 步：抽样核对
导入结束不等于数据正确。随机抽 10~20 行，与源文件比对：数字精度（小数位是否被截断）、日期时间值（时区偏移）、长文本（是否被截断或乱码）。重点抽查映射页中你手动改过类型的列。
第 2 步：从错误信息定位到行
导入过程中出现的所有异常都被 DataTransferState 模块统一收集为错误列表，任务结束后汇总展示。定位方法：
- 打开任务结果里的错误摘要，记下第一个错误的类型和涉及列；
- 用"每批 100 行"重新试跑，错误摘要会给出更小的批次范围，逐步二分；
- 在源文件中找到对应区间的行，检查是否有隐藏换行符、未闭合引号、超长字段——这三类问题肉眼难查，用文本编辑器的"显示不可见字符"功能可以快速暴露。
第 3 步：修复失败行的流程
- 如果失败行少：直接在源文件中修掉，然后用"忽略冲突"策略重跑整个文件，已入库的行会自动跳过；
- 如果失败行成片出现：说明是系统性配置问题（分隔符、编码、类型映射），回到导入前检查表重查，修完配置再重跑；
- 重跑前确认上一轮的失败批次没有部分入库，必要时先删掉该批次对应的数据再导。
快速定位：常见症状对照表
遇到具体报错或异常现象时，先查下表再动手：
| 症状 | 疑似原因 | 第一步动作 |
|---|---|---|
| 中文或重音字符变乱码 | 文件编码与设置不符 | 换编码重开文件找到能正常显示的编码，再填入导入设置 |
| 列数错位、字段串到相邻列 | 分隔符或引号字符设错 | 用文本编辑器确认实际分隔符，改设置后重新预览 |
| 日期写入后差 8 小时或格式错乱 | 源格式与目标期望格式不一致 | 源数据统一转成YYYY-MM-DD HH:MM:SS再导入 |
| 数值列整批报"cannot parse" | 数值含千位分隔符或货币符号 | 预处理去掉非数字字符，或在列映射处加转换 |
| 主键冲突、导入中途停 | 目标表已有同主键数据 | 切换加载策略为忽略冲突或先删后插，见上表选型 |
| 权限拒绝、写入失败 | 账号无 INSERT 权限 | 用有写权限的账号连接，或请 DBA 授权 |
要点回顾
- 预览环节 30 秒能发现 80% 的配置错误，编码、分隔符、表头三项确认后再开始导入。
- 主键策略按"是否允许重跑"选：忽略冲突最安全，先删后插最彻底。
- 批量大小从 1000 起步，遇批量错误就减半；每批提交，避免长事务。
- 失败行修复走"忽略冲突重跑"，成片失败则回查配置而不是逐行修。
最小行动建议：先拿 100 行的小样本完整跑一遍导入前、中、后三个阶段，确认三项检查、列映射和主键策略都没问题后，再执行全量数据导入。
【免费下载链接】dbeaverFree universal database tool and SQL client项目地址: https://gitcode.com/GitHub_Trending/db/dbeaver
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
