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