DBeaver 数据导入避坑指南：3 个关卡快速搞懂 CSV 导入失败

DBeaver 数据导入避坑指南：3 个关卡快速搞懂 CSV 导入失败

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

用 DBeaver 数据导入一个 10 万行的 CSV 文件，跑到一半弹出"日期无法解析""主键重复"，是新手最常遇到的场景。DBeaver 是免费的通用数据库工具，它的导入功能由数据传输模块驱动：文件先被解析成列，再逐行映射、转换、写入目标表。本文按数据流动的顺序，把一次导入拆成 3 个关卡：文件读得对、列映得对、约束过得去，每个关卡都按"现象 → 原因 → 处理 → 验证"四步展开，配一个可直接复现的小例子。

🔍 关卡一：文件读得对吗——分隔符与编码怎么设

现象：预览里整行数据向右串行——"姓名、年龄"两列的内容跑到了第三列；或者所有中文都变成了???。

原因：DBeaver 的 CSV 解析器（DataImporterCSV.java）严格按你配置的分隔符切分每一行，编码默认是 UTF-8。欧洲导出的 CSV 常用分号;分隔，Windows 下生成的中文 CSV 常用 GBK 编码，配置和文件对不上，切分结果自然错位。更隐蔽的是引号：一个带引号的城市字段"New York, NY"里藏着逗号，引号字符没配对时会被硬切成两列。

处理：导入向导第一步逐项确认四件事：分隔符（逗号、分号、制表符）、引号字符、首行是否作为列名（源码里对应top或none两个取值）、文件编码。中文乱码时，先把编码改成 GBK 再解析一次。

验证：解析完成后 DBeaver 会列出识别到的列名和类型。拿一个 3 列的小文件（姓名、年龄、城市）试跑，列名正确、预览值不串行，才进入下一关。

关卡二：列映得对吗——类型推断与列映射

现象：预览里123看着正常，写入整数列却报"转换失败"；或者2024-03-05被当成文本存进了日期列，之后按日期排序全部错位。

原因：CSV 里的值读出来全是字符串。DBeaver 默认采样前 100 行推断每列的类型，推断不出的就按字符串处理，落库前还要再按目标列的类型转换一次。类型推断只解决"源列长什么样"，"目标列要什么"必须靠映射界面确认。

处理：在列映射界面把源列与目标列逐列对齐，并显式指定目标类型，不要依赖自动推断。对带千分位的1,234.56，可以挂一个内置的表达式转换器先清洗再写入——转换器在 plugin.xml 中注册了表达式、常量、置空三类，具体行为以当前版本为准。

验证：先用前 100 行做小批量测试，导入后逐格比对目标表与源文件，重点看数字和日期两列，一致后再放全量。

关卡三：约束过得去吗——主键外键与错误定位

现象：导入到第 5 万行突然中断，提示主键重复；或者插入子表时报"找不到父记录"。

原因：源数据里存在与目标表重复的主键，或外键引用了尚未导入的父表。执行导入任务时，DTTaskHandlerTransfer.java 支持在导入前关闭引用完整性、结束后自动恢复，但重复主键这类冲突，仍需你在设置里选定处理策略。

处理：对重复行先选"跳过"策略跑一遍，观察跳过了多少行；外键问题按依赖顺序导入——先父表、后子表。整库迁移建议保存为"数据传输任务"而不是临时向导：过程中每条异常都会被记入 DataTransferState.java 维护的loadErrors列表，导入结束后可逐条查看，而不只是一个笼统的失败弹窗。

验证：三项都过才算完成——错误列表为空、SELECT COUNT(*)与源文件行数一致、抽查 3 条日期记录，时分秒与源文件完全相同。

✅ 收尾：一套 30 秒预览 + 100 行测试的标准动作

把"预览 3 列小文件 → 100 行小批量 → 全量 → 抽验"固化成肌肉记忆，就能把绝大多数失败挡在全量运行之前。现在就挑一个 10 行的小 CSV，按这 3 个关卡完整走一遍，把每个配置项亲手确认一次。

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