DBeaver 数据导入报错排查手册CSV 乱码、主键冲突等 6 类故障如何快速定位【免费下载链接】dbeaverFree universal database tool and SQL client项目地址: https://gitcode.com/GitHub_Trending/db/dbeaverDBeaver 数据导入到数据库的过程中报错信息往往只给出数据库层的异常而真正的诱因在文件侧或配置侧。本手册按报错现象分诊的方式组织先根据导入失败的表象判断问题属于哪一类再执行对应的处理动作避免逐条试错。涉及的核心实现集中在数据传输模块 plugins/org.jkiss.dbeaver.data.transfer/导入向导界面位于 plugins/org.jkiss.dbeaver.data.transfer.ui/。第 0 步用一张表确定故障类别遇到 DBeaver 导入报错先按下表完成分诊确定后再进入对应小节。多数导入失败属于前四类问题。报错/现象可能原因处理动作中文等字符写入后显示为乱码、?文件编码与导入编码设置不一致见 §1 数据导入编码设置数值/日期字段报无效值无法转换千位分隔符、日期格式与目标列类型不匹配见 §2 类型转换错误报主键/唯一键已存在duplicate key导入数据与库内已有记录冲突见 §3 DBeaver 主键冲突策略报外键约束违规foreign key violation被引用表的父记录尚未导入或不存在见 §4 外键依赖顺序列错位、空列、多出Column1之类列名分隔符、引号字符或标题行设置与文件不符见 §5 CSV 结构配置大文件导入中途超时、内存溢出、速度骤降批量过大、事务提交频繁见 §6 批量与事务控制⚠️ 分诊前先保留原始文件与报错文本。DBeaver 的导入不会把异常直接抛出终止而是统一收集到DataTransferStateDataTransferState.java的loadErrors列表中因此导入结束后的部分失败/错误条数提示就是该列表的汇总逐条查看比只看首条错误更有效。§1 数据导入编码设置解决 CSV 导入乱码先判断再处理乱码出现在预览界面说明编码设置问题乱码出现在导入后的数据库里说明导入时编码设置与预览时不一致或数据库连接的字符集有问题。CSV 导入器DataImporterCSV.java读取encoding属性决定文件解码方式未设置时按 UTF-8 处理。对应的处理动作在导入向导的文件设置页显式指定编码不要依赖默认值。UTF-8 为第一选择。Windows 下由 Excel 导出的中文 CSV尝试 GBK 编码源文件若是 UTF-8 带 BOMDBeaver 会经 BOM 探测自动处理无需手动指定。用文本编辑器先确认文件的实际编码再回到向导里设置两边必须一致。✅ 验证方法导入前先查看向导的预览页。预览正确而落库错误检查数据库连接的字符集参数预览就乱码改编码设置即可。§2 类型转换错误数值与日期字段数值和日期是类型转换报错的高发区两者处理思路相同让源数据的格式与目标列类型对齐而不是反复重试导入。数值列报无效值检查源数据是否含千位分隔符1,234,567、货币符号、全角数字。在列映射步骤确认目标列类型必要时导入前用文本工具批量清洗或在列映射中把该列目标类型调整为数值类型后再由数据库侧转换。日期列报格式错误在映射步骤明确指定源数据的日期格式。建议源文件统一使用YYYY-MM-DD HH:MM:SS的标准格式可减少一半以上的日期类报错。⚠️ 日期类错误有时不报错、只写错数据月份与日期互换。导入后抽样比对源文件与库内值确认无误再算完成。类型转换的执行逻辑见数据转换任务处理类 DTTaskHandlerTransfer.java导入配置中可自定义转换行为。§3 DBeaver 主键冲突三种冲突处理策略duplicate key / unique constraint 报错先确认一个前提目标表是否需要保留旧数据。再选择策略——策略行为适用场景忽略冲突跳过重复行写入其余数据增量导入旧数据为准更新现有用新数据覆盖已存在记录全量刷新新数据为准删除后插入删除冲突记录再插入需要完整替换语义时 操作顺序建议先用忽略冲突跑一次测试导入从错误条数确认重复数据的规模和质量再决定正式导入采用哪种策略。冲突处理选项位于导入向导的冲突设置项onConflict相关属性对应实现见 DatabaseTransferConsumer.java。§4 外键约束违规按依赖顺序导入外键报错的根因只有一个子表行引用的父表记录不存在。处理动作按顺序执行先导入父表无外键依赖或依赖层级更高的表再导入子表按依赖关系拓扑排序。若必须乱序导入确认数据库支持先禁用外键检查、导入后重建的操作生产环境慎用该手段。多表数据源迁移时把建表 DDL 与数据脚本分开管理先结构后数据。❌ 不要绕过约束后忘记重建外键检查这会让脏数据留在生产库中。§5 CSV 结构配置分隔符、引号与标题行列错位字段整体偏移一列、目标列名出现Column1这类默认名、引号被当作数据写入这三类现象同源于 CSV 解析配置。CSV 导入器支持的四个关键配置项配置项含义出错症状分隔符逗号/分号/制表符等整列错位、首列吞掉多列内容引号字符包裹含分隔符数据的字符引号原样入库、字段截断标题行首行是否为列名无/在首行出现Column1、表头被当数据空值标识哪些字符串视为 NULL空串入库而非 NULL处理动作拿到文件后先看前三行的原始内容注意区分分隔符在字段外和分隔符在引号内在向导里逐项对照设置然后用预览页核对列数和列名是否与预期一致。欧洲来源的 CSV 常以分号为分隔符默认逗号设置下必然错位属常见误区而非数据问题。§6 批量与事务控制大文件导入中断导入百万行级别数据中途失败或速度骤降时检查两项设置均在导入向导的目标端配置中批量大小每批提交的行数。过小导致事务提交频繁、性能差过大导致单批内存压力高。先取一个中等值如数千行测试再按表现调整。事务控制方式。按批提交可以控制回滚范围避免单批失败导致整份文件回滚重来。同时关注 JVM 堆内存设置导入过程中预览缓存和批量缓存都占用堆内存。仍失败时把文件切成 10 万行以内的分段分别导入可快速定位是某段数据的问题还是整体配置的问题。导入前核对清单每次 DBeaver 数据导入开始前按此清单过一遍可拦截大部分报错文件编码已显式指定且预览页无乱码分隔符、引号字符与文件实际内容一致标题行设置正确列名与目标表列一一对应数值、日期字段格式已与目标列类型对齐目标表已有数据时主键冲突策略已选定多表导入已按外键依赖排序批量大小与事务提交方式已按数据量设置当前账号具备目标库的写入权限执行顺序上坚持先小批量再全量用前 100 行验证全部配置确认预览、错误条数、落库值都正确后再执行完整导入。导入结束后对照DataTransferState汇总的错误条数决定是否二次补数并抽样核对关键字段。【免费下载链接】dbeaverFree universal database tool and SQL client项目地址: https://gitcode.com/GitHub_Trending/db/dbeaver创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DBeaver 数据导入报错排查手册：CSV 乱码、主键冲突等 6 类故障如何快速定位
DBeaver 数据导入报错排查手册CSV 乱码、主键冲突等 6 类故障如何快速定位【免费下载链接】dbeaverFree universal database tool and SQL client项目地址: https://gitcode.com/GitHub_Trending/db/dbeaverDBeaver 数据导入到数据库的过程中报错信息往往只给出数据库层的异常而真正的诱因在文件侧或配置侧。本手册按报错现象分诊的方式组织先根据导入失败的表象判断问题属于哪一类再执行对应的处理动作避免逐条试错。涉及的核心实现集中在数据传输模块 plugins/org.jkiss.dbeaver.data.transfer/导入向导界面位于 plugins/org.jkiss.dbeaver.data.transfer.ui/。第 0 步用一张表确定故障类别遇到 DBeaver 导入报错先按下表完成分诊确定后再进入对应小节。多数导入失败属于前四类问题。报错/现象可能原因处理动作中文等字符写入后显示为乱码、?文件编码与导入编码设置不一致见 §1 数据导入编码设置数值/日期字段报无效值无法转换千位分隔符、日期格式与目标列类型不匹配见 §2 类型转换错误报主键/唯一键已存在duplicate key导入数据与库内已有记录冲突见 §3 DBeaver 主键冲突策略报外键约束违规foreign key violation被引用表的父记录尚未导入或不存在见 §4 外键依赖顺序列错位、空列、多出Column1之类列名分隔符、引号字符或标题行设置与文件不符见 §5 CSV 结构配置大文件导入中途超时、内存溢出、速度骤降批量过大、事务提交频繁见 §6 批量与事务控制⚠️ 分诊前先保留原始文件与报错文本。DBeaver 的导入不会把异常直接抛出终止而是统一收集到DataTransferStateDataTransferState.java的loadErrors列表中因此导入结束后的部分失败/错误条数提示就是该列表的汇总逐条查看比只看首条错误更有效。§1 数据导入编码设置解决 CSV 导入乱码先判断再处理乱码出现在预览界面说明编码设置问题乱码出现在导入后的数据库里说明导入时编码设置与预览时不一致或数据库连接的字符集有问题。CSV 导入器DataImporterCSV.java读取encoding属性决定文件解码方式未设置时按 UTF-8 处理。对应的处理动作在导入向导的文件设置页显式指定编码不要依赖默认值。UTF-8 为第一选择。Windows 下由 Excel 导出的中文 CSV尝试 GBK 编码源文件若是 UTF-8 带 BOMDBeaver 会经 BOM 探测自动处理无需手动指定。用文本编辑器先确认文件的实际编码再回到向导里设置两边必须一致。✅ 验证方法导入前先查看向导的预览页。预览正确而落库错误检查数据库连接的字符集参数预览就乱码改编码设置即可。§2 类型转换错误数值与日期字段数值和日期是类型转换报错的高发区两者处理思路相同让源数据的格式与目标列类型对齐而不是反复重试导入。数值列报无效值检查源数据是否含千位分隔符1,234,567、货币符号、全角数字。在列映射步骤确认目标列类型必要时导入前用文本工具批量清洗或在列映射中把该列目标类型调整为数值类型后再由数据库侧转换。日期列报格式错误在映射步骤明确指定源数据的日期格式。建议源文件统一使用YYYY-MM-DD HH:MM:SS的标准格式可减少一半以上的日期类报错。⚠️ 日期类错误有时不报错、只写错数据月份与日期互换。导入后抽样比对源文件与库内值确认无误再算完成。类型转换的执行逻辑见数据转换任务处理类 DTTaskHandlerTransfer.java导入配置中可自定义转换行为。§3 DBeaver 主键冲突三种冲突处理策略duplicate key / unique constraint 报错先确认一个前提目标表是否需要保留旧数据。再选择策略——策略行为适用场景忽略冲突跳过重复行写入其余数据增量导入旧数据为准更新现有用新数据覆盖已存在记录全量刷新新数据为准删除后插入删除冲突记录再插入需要完整替换语义时 操作顺序建议先用忽略冲突跑一次测试导入从错误条数确认重复数据的规模和质量再决定正式导入采用哪种策略。冲突处理选项位于导入向导的冲突设置项onConflict相关属性对应实现见 DatabaseTransferConsumer.java。§4 外键约束违规按依赖顺序导入外键报错的根因只有一个子表行引用的父表记录不存在。处理动作按顺序执行先导入父表无外键依赖或依赖层级更高的表再导入子表按依赖关系拓扑排序。若必须乱序导入确认数据库支持先禁用外键检查、导入后重建的操作生产环境慎用该手段。多表数据源迁移时把建表 DDL 与数据脚本分开管理先结构后数据。❌ 不要绕过约束后忘记重建外键检查这会让脏数据留在生产库中。§5 CSV 结构配置分隔符、引号与标题行列错位字段整体偏移一列、目标列名出现Column1这类默认名、引号被当作数据写入这三类现象同源于 CSV 解析配置。CSV 导入器支持的四个关键配置项配置项含义出错症状分隔符逗号/分号/制表符等整列错位、首列吞掉多列内容引号字符包裹含分隔符数据的字符引号原样入库、字段截断标题行首行是否为列名无/在首行出现Column1、表头被当数据空值标识哪些字符串视为 NULL空串入库而非 NULL处理动作拿到文件后先看前三行的原始内容注意区分分隔符在字段外和分隔符在引号内在向导里逐项对照设置然后用预览页核对列数和列名是否与预期一致。欧洲来源的 CSV 常以分号为分隔符默认逗号设置下必然错位属常见误区而非数据问题。§6 批量与事务控制大文件导入中断导入百万行级别数据中途失败或速度骤降时检查两项设置均在导入向导的目标端配置中批量大小每批提交的行数。过小导致事务提交频繁、性能差过大导致单批内存压力高。先取一个中等值如数千行测试再按表现调整。事务控制方式。按批提交可以控制回滚范围避免单批失败导致整份文件回滚重来。同时关注 JVM 堆内存设置导入过程中预览缓存和批量缓存都占用堆内存。仍失败时把文件切成 10 万行以内的分段分别导入可快速定位是某段数据的问题还是整体配置的问题。导入前核对清单每次 DBeaver 数据导入开始前按此清单过一遍可拦截大部分报错文件编码已显式指定且预览页无乱码分隔符、引号字符与文件实际内容一致标题行设置正确列名与目标表列一一对应数值、日期字段格式已与目标列类型对齐目标表已有数据时主键冲突策略已选定多表导入已按外键依赖排序批量大小与事务提交方式已按数据量设置当前账号具备目标库的写入权限执行顺序上坚持先小批量再全量用前 100 行验证全部配置确认预览、错误条数、落库值都正确后再执行完整导入。导入结束后对照DataTransferState汇总的错误条数决定是否二次补数并抽样核对关键字段。【免费下载链接】dbeaverFree universal database tool and SQL client项目地址: https://gitcode.com/GitHub_Trending/db/dbeaver创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考