↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。

pg_fastload 1.0.0 发布:PostgreSQL 并行批量装载工具

发布于 2026-11-17,pg_fastload
相关开源软件

pg_fastload 1.0.0 是 PostgreSQL 的并行批量装载工具。项目方测试显示,其速度为 pg_bulkload 最佳模式的 1.58 倍、COPY 的 6.07 倍。它将装载流水线并行分配给后台工作进程,同时把整个装载保留在一个事务内。该工具在源码层面派生自 pg_bulkload 3.1.23,控制文件语法、TYPE 值、日志格式与 WRITER 模式保持不变。

要解决的问题

pg_bulkload 和 COPY 都在单个后端中完成读取、解析、形成元组及写入。在 16 核机器上,这会让其他 15 个核闲置,而解析通常是最昂贵的步骤。CSV 解析使用逐字节状态机,随后为每一列调用类型输入函数。

工作原理

装载分为四个阶段:读取输入、解析记录并分列、形成元组、插入。前三个阶段移入后台工作进程,插入仍由发起装载的后端串行完成:

一个读取工作进程 -> N 个解析工作进程 -> 主进程写入

实际使用时需要了解这些设计:

  • 输入文件只读取一次。 单个读取进程顺序扫描,通过 shm_mq 向工作进程传送数据块,工作进程不打开文件。总读取量始终等于文件大小,即使数据超过页缓存,也不会因重复读取抵消加速效果。
  • 仍然只有一个事务。 不创建第二条连接,不提前暴露未提交行;坏行会使整个装载失败,不会留下取决于工作进程时序的部分数据。
  • 遇到并行路径无法满足的 13 类条件时自动退回串行, 并以一条 INFO 说明原因,包括 FILTER、FORCE_NOT_NULL、显式 ENCODING、NOT NULL 或 CHECK 约束、PARSE_ERRORS 容错、STDIN 输入、TUPLE 与 FUNCTION 输入等。
  • 串行路径也做了优化。 不含引号或 CR 的记录用 memchr 批量分列,代替逐字节循环。

进度报告与导出

每次装载与导出都会在集群级视图 pgfastload.pg_fastload_progress 中发布行数、字节数、速率及耗时。如果总行数已知,例如指定有限的 LIMIT,或 TABLE= 导出可以使用 pg_class.reltuples 估算,还会显示百分比与预计剩余时间。任何会话都可跟踪长任务,也可以设置 PROGRESS_NOTICE=ON 持续接收 NOTICE。

导出日志还记录 MVCC 快照指纹(xmin / xmax / cid),使每个输出文件都能追溯到生成它的确切快照。pg_fastload_export() 可以将一张表或任意 SELECT 的结果导出为 CSV、BINARY 或 FIXED 格式。

测试结果

测试使用 1 GiB TPC-H lineitem CSV,共 7,375,042 行、16 vCPU、热缓存、WRITER=DIRECT、无索引,取三次运行中位数。每一项使用相同文件与相同的空表。

配置 耗时 对比串行 对比 COPY FROM PARALLEL=OFF 5.81 s 1.00x 1.43x PARALLEL_WORKERS=4 1.58 s 3.68x 5.27x 默认(15 个工作进程) 1.37 s 4.24x 6.07x 参考:上游 pg_bulkload 6.98 s 参考:COPY ... FROM 8.32 s 参考:COPY 到 UNLOGGED 表 7.51 s

完整装载器、写入模式与格式组合的结果如下,交替运行三轮并取中位数:

CSV BINARY FIXED 上游 pg_bulkload BUFFERED 9.22 4.08 3.95 上游 pg_bulkload DIRECT 6.98 1.62 1.59 上游 pg_bulkload PARALLEL 6.63 1.39 1.42 pg_fastload PARALLEL=OFF 5.84 1.58 1.63 pg_fastload 8 个工作进程 1.42 0.88 0.90 pg_fastload 默认 1.40 0.90 0.93 COPY ... FROM 8.34 不适用 不适用

上游最快的写入模式其实是 PARALLEL,比其 DIRECT 快约 13%。因此,准确的整体比较是比上游最佳模式快 1.58 倍、比最慢模式快 4.4–4.6 倍,而非只比较 DIRECT 时得出的 2 倍以上。

导出也有类似效果:740 万行(1.13 GiB)串行用时 4.08 秒,15 个工作进程用时 0.42 秒,即服务端 COPY TO 的 9.33 倍。导出扫描使用一个 MVCC 快照,并将该快照序列化后传给并行工作进程,因此并发写入期间的导出仍然一致且可复现。

测试方法、公平性控制与完整结果(冷缓存、定长格式、导出及历史测试档位)见仓库中的 docs/BENCHMARK.md;所有原始运行日志随发布归档提供。

与上游 pg_bulkload 3.1.23 的区别

  • 并行 CSV 和并行定长装载,相对于上游最佳模式分别为 4.7 倍和 1.6 倍;语义相同的串行路径为上游的 1.22 倍。
  • 装载与导出进度视图,包含百分比、预计剩余时间与 NOTICE 流。
  • SKIP_INDEX=ON 在装载事务内删除目标表的次级索引,并输出原样的 CREATE INDEX 语句供重建;在带索引的表上可节省约一半装载时间。
  • 无索引表不再进行无用的暂存工作。
  • 提供阶段级性能分析构建,并以一个分支支持 PostgreSQL 15 至 19。

兼容性与限制

PARALLEL=ON、PARALLEL_WORKERS 与 SKIP_INDEX 是新增选项,其余行为兼容 pg_bulkload。

  • 一个分支支持 PostgreSQL 15、16、17、18、19,版本差异通过 PG_VERSION_NUM 在编译时处理。
  • 装载时,一个 B-tree 索引的维护成本约为每 GiB 1.9 秒,且不能并行。SKIP_INDEX=ON 自动完成删除并提示重建的流程;主键、唯一约束和排他约束的支撑索引会被拒绝删除,不会静默移除。
  • 主进程的串行插入构成性能下限:达到每 GiB 1.37 秒后,剩余瓶颈是页面填充与 WAL,而非解析。

欢迎反馈,尤其是在其他硬件、超过内存的数据集,或更频繁触发串行回退的工作负载上的反例。

致意, Yuansong