pgloader命令语法详解：高效数据迁移工具使用指南

概述

pgloader是一款功能强大的数据迁移工具，它采用领域特定语言(DSL)来定义复杂的数据加载场景。本文将深入解析pgloader的命令语法结构，帮助用户掌握如何高效地配置数据迁移任务。

基本命令结构

pgloader的命令遵循统一的语法框架，主要包含以下几个核心部分：

LOAD <数据源类型>
     FROM <数据源URL>
     [ HAVING FIELDS <源级选项> ]
     INTO <PostgreSQL连接URL>
     [ TARGET TABLE [ "<模式>" ]."<表名>" ]
     [ TARGET COLUMNS <列及选项> ]

[ WITH <加载选项> ]

[ SET <PostgreSQL设置> ]

[ BEFORE LOAD [ DO <SQL语句> | EXECUTE <SQL文件> ] ... ]
[ AFTER LOAD [ DO <SQL语句> | EXECUTE <SQL文件> ] ... ]
;

核心子句详解

FROM子句

FROM子句指定数据来源，不同数据源类型支持的格式各异：

• CSV数据源支持内联数据、标准输入、文件名、带引号的文件名以及文件名匹配模式
• MySQL数据源则仅支持MySQL数据库URI规范

INTO子句

INTO子句定义PostgreSQL目标连接，必须包含目标表名。关键特性包括：

• 目标表必须已存在于PostgreSQL中
• 支持模式限定表名(如"schema"."table")
• 可选的目标列列表，可指定列名、数据类型和转换表达式

转换表达式支持Common Lisp语法，运行时会被编译为本地代码，实现灵活的数据转换。

WITH子句

WITH子句用于设置加载选项，语法格式为：

• key = value
• use option
• do not use option

所有数据源都支持的通用选项包括：

• 错误处理：on error stop或on error resume next
• 批处理控制：batch rows和batch size
• 预取设置：prefetch rows

SET子句

SET子句用于设置PostgreSQL会话参数，格式为： 参数名 = '值'（逗号分隔列表）

加载前后操作

pgloader提供了灵活的钩子机制，可在数据加载前后执行自定义操作：

BEFORE LOAD

• DO：直接执行SQL语句（使用$$分隔符）
• EXECUTE：执行SQL文件

典型用途：创建目标表结构

AFTER LOAD

• DO：数据加载完成后执行的SQL
• EXECUTE：执行SQL文件

典型用途：创建索引、约束或重新启用触发器

AFTER CREATE SCHEMA

• DO：模式创建后执行的SQL
• EXECUTE：执行SQL文件

典型用途：表分区等高级操作

连接字符串规范

PostgreSQL连接URI格式： postgresql://[用户[:密码]@][主机][:端口][/数据库][?选项=值&...]

关键组成部分：

1. 用户认证：

   • 用户名可包含任何字符，特殊字符需转义
   • 密码处理遵循PostgreSQL标准，支持环境变量和密码配置文件

2. 网络位置：

   • 支持主机名、IPv4地址或Unix域套接字路径
   • 特殊语法：unix:/路径指定非默认套接字

3. 数据库名：

   • 需符合标识符规范（字母开头，可包含字母、数字和特定标点）

4. 选项参数：

   • 支持sslmode、host、port等关键参数
   • sslmode可选值：disable/allow/prefer/require

高级特性

正则表达式支持

pgloader在多处支持正则表达式，语法特点：

• 以~开头
• 支持多种分隔符对：//、[]、{}等
• 表达式内容中可包含除结束分隔符外的任何字符

注释语法

支持两种注释风格：

1. 单行注释：-- 注释内容
2. 多行注释：/* 注释内容 */

批处理行为控制

关键批处理选项：

• batch rows：每批最大行数（默认25,000）
• batch size：每批最大内存占用（默认20MB）
• prefetch rows：每个读取线程预取行数（默认100,000）

批处理会在达到行数或大小限制时提交，以先到者为准。

Mustache模板支持

pgloader集成了Mustache模板系统，支持：

• 从环境变量获取值：{{VAR}}
• 通过INI文件提供上下文
• 动态构建命令参数

最佳实践建议

1. 数据准备阶段：

   • 使用BEFORE LOAD创建表结构
   • 考虑禁用触发器和约束以提高加载速度

2. 性能调优：

   • 根据硬件配置调整batch rows和batch size
   • 合理设置workers和concurrency参数

3. 数据转换：

   • 利用TARGET COLUMNS实现复杂转换逻辑
   • 考虑使用AFTER LOAD进行数据后处理

4. 错误处理：

   • 测试阶段使用on error resume next收集问题
   • 生产环境建议使用on error stop确保数据一致性

通过掌握这些命令语法和选项，用户可以充分发挥pgloader的强大功能，实现高效可靠的数据迁移任务。