pgloader 学习（五）pgloader 参考手册

pgloader将各种来源的数据加载到PostgreSQL中。它可以转换动态读取的数据，并在加载前后提交原始SQL。
它使用COPY PostgreSQL协议将数据流式传输到服务器，并通过填充一对reject.dat和reject.log文件来管理错误
pgloader 的操作，可以使用命令行参数，或者通过读取文件中定义的dsl
格式：

 

pgloader commands.load

或者使用参数：

pgloader SOURCE TARGET

参数说明

pgloader参数可以根据需要加载文件，也可以是特定输入文件的几个连接字符串。

源连接字符串

格式：

format:///absolute/path/to/file.ext

format://./relative/path/to/file.ext

format 可以是 csv, fixed, copy, dbf, db3 或者ixf

db://user:pass@host:port/dbname

db 可以是sqlite、mysql、mssql
当使用基于文件的源格式时，pgloader还支持从http位置本地获取文件并在需要时解压缩存档。
在这种情况下，必须使用-type选项指定文件的预期格式
另请注意，某些文件格式需要描述一些实现细节，例如要读取的列和分隔符以及从csv加载时的引用。
对于更复杂的加载方案，您需要使用本文档后面描述的语法编写完整的fledge加载命令。

目标连接字符串

对于目标字符串会在后边详细介绍

工具选项

查询选项

-h，-help 显示命令用法摘要并退出。

-V，-version 显示pgloader版本字符串并退出。

-E，-list-encodings 列出此版本的pgloader中的已知编码。

-U，-upgrade-config 使用pgloader版本2.x中使用的INI语法将命令行中的给定文件解析为pgloader.conf文件 ，并在标准输出上输出pgloader的新命令语法。

常规选项

这些选项用于在加载数据时调整pgloader行为

-v，-verbose 显示比较可用信息

-q，-quiet 退出

-d，-debug 显示调试级别信息消息。

-D，-root-dir 设置根工作目录（默认为“/ tmp / pgloader”）。

-L，-logfile 设置pgloader日志文件（默认为“/tmp/pgloader/pgloader.log”）。

–log-min-messages 日志消息进入日志文件所需的最低级别的详细程度。关键，日志，错误，警告，通知，信息或调试之一。

–client-min-messages 日志消息进入控制台所需的最低级别详细程度。关键，日志，错误，警告，通知，信息或调试之一。

-S，-summary 用于复制摘要输出的文件名。相对时，文件名扩展为* root-dir *。

文件名的格式默认为人类可读。通过指定扩展名为resp的文件名，可以使用机器友好格式（如CSV， COPY（PostgreSQL自带的COPY格式）或JSON）输出。的.csv，.copy或以.json。

-l <file>， - load-lisp-file <file>

在读取命令之前指定lisp <file>进行编译并加载到pgloader映像中，允许定义额外的转换函数。这些函数应该在pgloader.transforms包中定义。此选项可在命令行中出现多次。

-dry-run

允许测试.load文件而不实际尝试加载任何数据。调试它直到它没问题是有用的，特别是修复连接字符串。

-on-error-stop

改变pgloader行为：而不是试图聪明地处理错误处理并继续加载好的数据，分离掉坏的数据，只要PostgreSQL拒绝发送给它的任何东西就停止。用于调试数据处理，转换功能和特定类型转换。

-self-upgrade <directory>

指定一个<directory>在哪里找到pgloader源，这样它所做的第一件事就是动态加载（并编译成机器代码）另一个版本的自身，通常是一个像最新的git checkout这样的新版本。

–no-ssl-cert-verification

使用OpenSSL选项接受本地颁发的服务器端证书，避免以下错误消息：

SSL verify error: 20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY

解决SSL问题的正确方法是使用可信证书。有时虽然在修复信任证书链的同时使用pgloader设置取得进展是有用的，但也许是由另一个团队。这个选项很有用。

命令行操作选项

参数仅在，使用命令行运行数据加载操作时生效

–with "option"

允许从命令行设置选项。您可以根据需要多次使用该选项。option参数必须遵循SOURCE规范 的源类型的WITH子句

–set "guc_name='value'"

允许从命令行设置PostgreSQL配置。请注意，选项解析与从SET命令子句中使用时相同，特别是必须使用单引号将guc值括起来

–field "…"

允许设置源字段定义。字段按命令行中给出的顺序累积。可以 在源文件中的每个字段使用-field选项，或者用逗号分隔字段定义，就像在HAVING FIELDS子句中那样

–cast "…"

允许设置特定的强制转换规则以加载数据。

–type csv|fixed|db3|ixf|sqlite|mysql|mssql

如果SOURCE解析不满意，则允许强制源类型。

–encoding <encoding>

设置源文件的编码以从中加载数据。

–before <filename>

解析SQL查询的给定文件名，并在从源加载数据之前对目标数据库运行它们。查询由pgloader本身解析：它们需要以分号（;）结束，文件可能包含i或ir命令以包含另一个文件

–after <filename>

解析SQL查询的给定文件名，并在从源加载数据后对目标数据库运行它们。查询的解析方式与-before选项相同

批量以及重试操作

要将数据加载到PostgreSQL，pgloader使用COPY流协议。虽然这是加载数据的更快方式，但COPY有一个重要的缺点：
一旦PostgreSQL发送任何数据发送到它的错误，无论出现什么问题，PostgreSQL都会拒绝整个数据集
为了解决这个问题，pgloader将数据分成每批 25000行，这样当出现问题时，它只影响那么多行数据。当COPY流发生时，
每个批处理都保存在内存中，以便能够在某些情况发生时处理错误
当PostgreSQL拒绝整个批处理时，pgloader会记录错误消息，然后通过以较小批量重试批处理行来将坏行与已接受的行隔离。
为此，pgloader 从失败的COPY中解析CONTEXT错误消息，因为消息包含批处理中发现错误的行号，格式如下：

 

CONTEXT: COPY errors, line 3, column b: "2006-13-11"

使用该信息，pgloader将在错误之前重新加载批处理中的所有行，将错误的行记录为拒绝，然后尝试在单次尝试中加载剩余的批次，
这可能包含或可能不包含其他错误数据。
在包含被拒绝行的加载结束时，您将在root-dir位置找到两个文件，这两个文件位于与安装程序的目标数据库相同的目录下。文件名是目标表，
对于被拒绝的数据，它们的扩展名为.dat;对于包含有关被拒绝数据的完整PostgreSQL客户端日志的文件，它们的扩展名为.log。
可以使用以下WITH选项来控制pgloader批处理行为：

• on error stop, on error resume next
  此选项控制pgloader是否正在使用构建批量数据。批处理实现允许pgloader通过发送PostgreSQL再次接受的数据并通过保留PostgreSQL拒绝
  的数据来恢复错误。要启用重试数据并加载好的部件，请使用下一个错误恢复选项，这是基于文件的数据加载（例如CSV，IXF或DBF）的默认选项 。
  从其他RDMBS技术迁移时，最好具有可重现的加载过程。在这种情况下，可以在错误停止时使用并修复转换规则，数据转换功能或输入数据，
  直到迁移完成。这就是on error stop, on error resume next是SQLite，MySQL和MS SQL源类型的默认值。

关于性能的注意事项

它使用的基本架构是旧的Unix管道模型，其中一个线程负责加载数据（读取CSV文件，查询MySQL等）并将预处理的数据填充到队列中。
另一个线程从队列中提取，对输入数据应用更多转换，并使用COPY协议将最终结果传输到PostgreSQL。

关于并行处理

pgloader使用几个并发任务来处理正在加载的数据：

• 读取器任务读入数据并将其推送到队列中，
• 最后一个写入任务从队列中提取并将raw格式化为批处理的PostgreSQL COPY格式（这样就可以重新尝试失败的批处理，而无需再次从源读取数据），
  然后使用COPY将数据发送到PostgreSQL协议。
  我们允许worker同时在单个表的上下文中同时处于活动状态。单个工作单元由几种worker组成：
• 一个reader从源头获取原始数据，
• N个worker准备并将数据发送到PostgreSQL。
  这里的N设置为并发参数：CONCURRENCY为2，我们启动（+ 1 2）= 3个并发任务，并发为4我们启动（+ 1 4）= 5个并发任务，其中只有worker可以同时活跃。
  默认值为workers = 4，从数据库源加载时concurrency = 1，worker = 8，从其他东西（当前是文件）加载时concurrency = 2。这些默认值是任意的
  由于pgloader启动的CREATE INDEX线程只等到PostgreSQL完成实际工作，因此这些线程不计入并发级别
  默认情况下，在源架构中找到与每个表的最大索引数一样多的CREATE INDEX线程。可以将max parallel create index WITH选项设置为另一个数字，
  以防其中有太多要创建的数字。

pgloader 命令语法

pgloader实现了一种特定于域的语言，允许设置复杂的数据加载脚本，处理计算列和输入数据的动态清理。对于更复杂的数据加载方案，
需要了解DSL的语法
语法规则：

 

LOAD <source-type>

         FROM <source-url>

       [ HAVING FIELDS <source-level-options> ]

             INTO <postgresql-url>

       [ TARGET TABLE [ "<schema>" ]."<table name>" ]

       [ TARGET COLUMNS <columns-and-options> ]

​

    [ WITH <load-options> ]

​

    [ SET <postgresql-settings> ]

​

[ BEFORE LOAD [ DO <sql statements> | EXECUTE <sql file> ] ... ]

[ AFTER LOAD [ DO <sql statements> | EXECUTE <sql file> ] ... ]

    ;

主要子句是每个命令实现的LOAD，FROM，INTO和WITH子句。然后，某些命令会实现SET命令或某些特定子句，例如CAST子句

使用Mustache

pgloader 实现了Mustache 模版引擎，可以方便的进行动态配置
pgloader 具有一个特性就是可以获取os 系统的环境变量，参考如下：

export DBPATH=sqlite/sqlite.db

pgloader ./test/sqlite-env.load

模版使用环境变量

load database

     from '{{DBPATH}}'

     into postgresql:///pgloader;

通用子句

• from
  该FROM子句指定在何处读取从数据
• into
  PostgreSQL连接URI必须包含要将数据加载到的目标表的名称。该表必须已在PostgreSQL中创建，并且名称可能是模式限定的。
  然后INTO选项还支持可选的逗号分隔的目标列列表，它们是输入字段的名称或目标列名称的空格分隔列表，其PostgreSQL数据
  类型和 USING表达式
  在使用表达可以是任何有效的Common Lisp形式，并且将与当前包设置要被读取pgloader.transforms，这样就可以使用在包中定义的功能，
  例如与动态加载功能-load命令行参数。
  每个USING表达式在运行时编译为本机代码。
  此功能允许pgloader使用该投影的自定义代码将CSV文件中的任意数量的字段加载到数据库中可能不同数量的列中
• with
  应用于命令的一组选项，使用以下任一的全局语法：
  格式

 

key = value

use option

do not use option

所有数据源特定命令都支持以下选项：

on error stop, on error resume next

batch rows = R

batch size = … MB

prefetch rows = …

此外，还提供以下设置：

workers = W

concurrency = C

max parallel create index = I

• set
  此子句允许指定要为pgloader打开的所有会话设置的会话参数。它需要一个参数名称列表，等号，然后单引号值作为逗号分隔列表。
  pgloader不验证参数的名称和值，它们按原样给予PostgreSQL。
• BEFORE LOAD DO
  在从CSV文件加载数据之前，您可以对数据库运行SQL查询。最常见的SQL查询是CREATE TABLE IF NOT EXISTS，以便可以加载数据。
  每个命令必须以美元引用：它必须以双美元符号$$开头和结尾。然后用美元引用的查询以逗号分隔。在最后一次SQL查询后，不应该有
  额外的标点符号。
• BEFORE LOAD EXECUTE
  与BEFORE LOAD DO子句中的行为相同。允许您从SQL文件中读取SQL查询。实现对PostgreSQL美元引用的支持以及i和ir包括psql批
  处理模式中的特性（它们是相同的东西）
• AFTER LOAD DO
  与BEFORE LOAD DO格式相同，在加载完成后，将执行该部分中找到的美元引用查询。此处是创建索引和约束或重新启用触发器的最佳时机。
• AFTER LOAD EXECUTE
  与AFTER LOAD DO子句中的行为相同。允许您从SQL文件中读取SQL查询。实现对PostgreSQL美元引用的支持以及i和ir包括psql批处理模式
  中的特性（它们是相同的东西）
• AFTER CREATE SCHEMA DO
  与BEFORE LOAD DO相同的格式，在该部分中找到的美元引用的查询在pgloader创建模式之后，以及在加载数据之前执行。此处是ALTER
  TABLE的最佳时机，或者在pgloader的基础上做一些自定义实现，比如分区与BEFORE LOAD DO相同的格式，在该部分中找到的美元引用的
  查询在pgloader创建模式之后，以及在加载数据之前执行。此处是ALTER TABLE的最佳时机，或者在pgloader的基础上做一些自定义实现，
  比如分区
• AFTER CREATE SCHEMA EXECUTE
  与AFTER CREATE SCHEMA DO子句中的行为相同。允许您从SQL文件中读取SQL查询。实现对PostgreSQL美元引用的支持以及i和ir包括
  psql批处理模式中的特性（它们是相同的东西）。
• 连接字符串
  参考格式：

 

postgresql://[user[:password]@][netloc][:port][/dbname][?option=value&...]

• 注释
  可以包含以下格式的注释

 

以 – 定界符开始与当前行的结尾结束的评论,

定界符 /* and */ 分别开始和结束注释，可以在命令中间找到或跨越几行

• 批处理操作选项
  支持以下配置

 

batch rows

将数值作为参数，用作批处理中允许的最大行数。默认值为25 000，可以更改为尝试具有更好的性能特征或控制pgloader内存使用情况;

batch size

将内存单元作为参数，例如20 MB，即其默认值。可接受的乘数是kB，MB，GB，TB和PB。这种情况很重要，以免混淆位与字节，我们这里只讨论字节。

prefetch rows

将数值作为参数，默认为100000。这是允许pgloader在每个读者线程的内存中读取的行数。请参阅workers设置，了解允许同时运行多少个读取器线程。

参考资料

https://pgloader.readthedocs.io/en/latest/pgloader.html