如何把 MySQL 与 CSV 数据快速迁入 PostgreSQL：pgloader 实操指南-平芜编程栈

如何把 MySQL 与 CSV 数据快速迁入 PostgreSQL：pgloader 实操指南

【免费下载链接】pgloaderMigrate to PostgreSQL in a single command!项目地址: https://gitcode.com/gh_mirrors/pg/pgloader

pgloader 是一个面向 PostgreSQL 的数据入库工具：它走 COPY 协议把数据流式灌进目标库，整库搬过去时可以自动发现源端表结构、建索引和外键；遇到出问题的行，默认策略是把坏行写进 reject 文件继续往下走，而不是一棒子打死整批数据。适合刚接手库、要把旧数据搬进 PostgreSQL 的开发者与 DBA。

适用场景	不适用场景
判断	SQLite / MySQL / MSSQL / PostgreSQL 整库搬到 PostgreSQL；CSV、定长文件等入库	目标不是 PostgreSQL 系产品；需要复杂多步清洗的 ETL 流程
一句话理由	一条命令完成建表、建索引与数据加载，出错行自动隔离，过程可重复执行	需要把数据改写成分布式拓扑或对接非 SQL 引擎时，另选工具

最小可运行路径：3 步跑通第一次入库

1. 安装并验证环境

v4 是 Clojure 重写版，交付物是一个自包含 JAR，需要 Java 21 或更高版本；不想跟 JVM 打交道的话，Debian/Ubuntu 仓库里仍可直接装 v3。装完后跑这条命令，预期返回版本号而不是报错：

java -jar pgloader.jar --version

2. 一条最简命令完成整库搬迁

下面这条命令会把一个 SQLite 库的表、索引、外键和注释全部搬到目标 PostgreSQL 库，是官方 quickstart 里最短的整库路径：

createdb newdb pgloader ./test/sqlite/sqlite.db postgresql:///newdb

3. 验证数据已落库

用 psql 连上新库，确认表建出来了、行数对得上。预期先看到表清单，再看到一个与源库一致的行数：

psql -d newdb -c '\dt' psql -d newdb -tc 'select count(*) from "表名";'

如果行数对不上，不要急着怀疑工具，先翻运行日志里的 reject 计数，看是不是有一批行被拒收了。

100 万行级库的迁移速度，先看这两个参数

参数怎么定，按数据量级对号入座即可：

数据量级	建议参数	判断依据
小文件 / 小表（<10 万行）	默认值	COPY 流式加载本身很快，调参收益不明显
百万到千万行	`WITH batch rows = 100000, prefetch rows = 100000`	批太小提交频繁，批太大单条失败回滚面大，取折中
大表且目标机空闲	再叠加`workers = 4`、`concurrency = 4`	多表并行加载；先确认磁盘 IO 不是瓶颈，否则加了反而更慢

调优顺序：先动batch rows，再动workers，两个都不够再看目标库的maintenance_work_mem。
v4 基于 JVM，整库数据量大时记得用-Xmx调堆，官方 README 明确这是替代 v3 Lisp 堆的方案。
记住默认值：数据库源默认on error stop，一错就停；文件源默认on error resume next，坏行落 reject 文件后继续。

迁移完成后如何校验数据

看运行日志与 summary 文件（--summary指定输出位置）里的 rejected 计数，并确认 reject 文件为空或行数符合预期。
源库与目标库逐表做行数比对：

SELECT relname, n_live_tup FROM pg_stat_user_tables ORDER BY 1;

挑一两张关键表抽样核对：按主键取几条，逐字段比对；对日期、金额列额外确认转换后的取值是否合理（比如 MySQL 的0000-00-00是否按预期变成了 NULL）。

迁移失败时怎么退回到安全状态

动真库之前，先pg_dump备份目标库，并记下本次运行使用的.load文件与命令行。
默认策略下，pgloader 在目标端先 DROP 再 CREATE，所以最省事的回滚就是删库重建后重跑，整条命令是幂等可重复的。
想"错一行就整体停"，加--on-error-stop，让第一次失败暴露问题，而不是跑完才发现半成品。
正式跑之前用--dry-run只查连接不写数据，把网络、账号、SSL 这类低级错误挡在前面。

迁移失败时先看哪 5 种现象

现象	最可能的原因	处理动作
连不上目标库	账号、网络或 SSL 配置不对	看日志第一条错误，先跑`--dry-run`
`invalid byte sequence for encoding`	源端字符集与目标 UTF8 不符	检查`--list-encodings`，在连接串或配置里指定源编码
唯一键冲突	目标表已有同主键数据	确认是否该用 drop/truncate 策略清空后重灌
JVM 堆内存溢出	v4 下`-Xmx`默认值不够	调大`-Xmx`，同时减小`batch rows`
速度比预期慢	批太小或没开并行	按上一节顺序改`batch rows`与`workers`